# Twilio

## Get Twilio sub-account

> Retrieve the Twilio sub-account for this workspace. Requires \`Workspace.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SubAccountResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"account_sid":{"type":"string","title":"Account Sid"},"friendly_name":{"type":"string","title":"Friendly Name"},"environment":{"type":"string","title":"Environment"},"twiml_app_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twiml App Sid"},"status":{"type":"string","title":"Status","default":"active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","account_sid","friendly_name","environment","twiml_app_sid","created_at","updated_at"],"title":"SubAccountResponse"}}},"paths":{"/v1/{workspace_id}/twilio/sub-account":{"get":{"tags":["Twilio"],"summary":"Get Twilio sub-account","description":"Retrieve the Twilio sub-account for this workspace. Requires `Workspace.view` permission.","operationId":"get-twilio-sub-account","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubAccountResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"No sub-account provisioned."}}}}}}
```

## Provision Twilio sub-account

> Create a Twilio sub-account for this workspace with TwiML App. Idempotent — returns existing if already provisioned. Requires \`Workspace.update\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SubAccountResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"account_sid":{"type":"string","title":"Account Sid"},"friendly_name":{"type":"string","title":"Friendly Name"},"environment":{"type":"string","title":"Environment"},"twiml_app_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twiml App Sid"},"status":{"type":"string","title":"Status","default":"active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","account_sid","friendly_name","environment","twiml_app_sid","created_at","updated_at"],"title":"SubAccountResponse"}}},"paths":{"/v1/{workspace_id}/twilio/sub-account":{"post":{"tags":["Twilio"],"summary":"Provision Twilio sub-account","description":"Create a Twilio sub-account for this workspace with TwiML App. Idempotent — returns existing if already provisioned. Requires `Workspace.update` permission.","operationId":"provision-twilio-sub-account","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubAccountResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Workspace not found."},"503":{"description":"Twilio provisioning not configured."}}}}}}
```

## Search available phone numbers

> Search available phone numbers for purchase on this workspace's Twilio sub-account. Requires \`PhoneNumber.create\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SearchAvailableNumbersResponse":{"properties":{"numbers":{"items":{"$ref":"#/components/schemas/AvailableNumber"},"type":"array","title":"Numbers"}},"type":"object","required":["numbers"],"title":"SearchAvailableNumbersResponse"},"AvailableNumber":{"properties":{"phone_number":{"type":"string","title":"Phone Number"},"friendly_name":{"type":"string","title":"Friendly Name"},"locality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locality"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"capabilities":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Capabilities","default":{}}},"type":"object","required":["phone_number","friendly_name"],"title":"AvailableNumber"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/twilio/phone-numbers/available":{"get":{"tags":["Twilio"],"summary":"Search available phone numbers","description":"Search available phone numbers for purchase on this workspace's Twilio sub-account. Requires `PhoneNumber.create` permission.","operationId":"search-available-phone-numbers","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US","title":"Country"}},{"name":"area_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Area Code"}},{"name":"contains","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contains"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchAvailableNumbersResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"No sub-account provisioned."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Purchase a phone number

> Purchase a phone number on this workspace's Twilio sub-account and register it. Requires \`PhoneNumber.create\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PurchasePhoneNumberRequest":{"properties":{"phone_number":{"type":"string","maxLength":16,"title":"Phone Number"},"display_name":{"type":"string","maxLength":256,"title":"Display Name","default":""},"capabilities":{"items":{"type":"string","enum":["inbound","outbound"]},"type":"array","title":"Capabilities","default":["inbound","outbound"]}},"type":"object","required":["phone_number"],"title":"PurchasePhoneNumberRequest"},"PhoneNumberPurchaseResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"phone_number":{"type":"string","title":"Phone Number"},"display_name":{"type":"string","title":"Display Name"},"provider_phone_sid":{"type":"string","title":"Provider Phone Sid"},"status":{"type":"string","title":"Status"},"capabilities":{"items":{"type":"string","enum":["inbound","outbound"]},"type":"array","title":"Capabilities"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","workspace_id","phone_number","display_name","provider_phone_sid","status","capabilities","created_at"],"title":"PhoneNumberPurchaseResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/twilio/phone-numbers/purchase":{"post":{"tags":["Twilio"],"summary":"Purchase a phone number","description":"Purchase a phone number on this workspace's Twilio sub-account and register it. Requires `PhoneNumber.create` permission.","operationId":"purchase-phone-number","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasePhoneNumberRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberPurchaseResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"No sub-account provisioned."},"409":{"description":"Phone number already registered."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Release a phone number

> Release a phone number back to Twilio and remove from workspace. Requires \`PhoneNumber.delete\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}}},"paths":{"/v1/{workspace_id}/twilio/phone-numbers/{phone_number_id}/release":{"delete":{"tags":["Twilio"],"summary":"Release a phone number","description":"Release a phone number back to Twilio and remove from workspace. Requires `PhoneNumber.delete` permission.","operationId":"release-phone-number","parameters":[{"name":"phone_number_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Phone Number Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Phone number not found."},"422":{"description":"No provider SID on number."}}}}}}
```