{"openapi":"3.1.0","info":{"title":"cloudNumbering API","description":"API for purchasing and managing phone numbers and sending SMS messages","version":"1.1.0"},"servers":[{"url":"https://api.cloudnumbering.com"}],"security":[{"OAuth2":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.cloudnumbering.com/v1/oauth/token","refreshUrl":"https://api.cloudnumbering.com/v1/oauth/token","scopes":{}}}}},"schemas":{"AuthTokenResponseV1_1":{"type":"object","properties":{"accessToken":{"type":"string","description":"Bearer access token in camelCase format","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"refreshToken":{"type":"string","description":"Refresh token returned for refreshable grants","example":"RT1234567890abcdef"},"tokenType":{"type":"string","description":"OAuth2 token type in camelCase format","example":"Bearer"},"expiresIn":{"type":"number","description":"Seconds until the access token expires in camelCase format","example":3600},"access_token":{"type":"string","description":"Bearer access token in snake_case format","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"refresh_token":{"type":"string","description":"Refresh token in snake_case format","example":"RT1234567890abcdef"},"token_type":{"type":"string","description":"OAuth2 token type in snake_case format","example":"Bearer"},"expires_in":{"type":"number","description":"Seconds until the access token expires in snake_case format","example":3600},"scope":{"type":"string","description":"Granted OAuth2 scope","example":"customer-api"}},"required":["accessToken","tokenType","expiresIn","access_token","token_type","expires_in"]},"AuthTokenErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"OAuth2 error code","example":"invalid_client"},"error_description":{"type":"string","description":"Human-readable error description","example":"Invalid client credentials"}},"required":["error","error_description"]},"Organisation":{"type":"object","properties":{"sid":{"type":"string","example":"OR12345678901234567890123456789012"},"name":{"type":"string","example":"My Organisation"},"tradingName":{"type":"string","example":"My Trading Name"},"addr1":{"type":"string","example":"123 Fake Street"},"addr2":{"type":"string","example":""},"city":{"type":"string","example":"Exeter"},"state":{"type":"string","example":"Devon"},"postcode":{"type":"string","example":"EX1 111"},"countryIso":{"type":"string","example":"GB"},"registeredCountryIso":{"type":"string","example":"GB"},"vatNumber":{"type":"string","example":"GB123456789"},"typeOfBusiness":{"type":"string","example":"Software"},"productUseCase":{"type":"string","example":"Internal"},"website":{"type":"string","example":"https://example.com"},"productDescription":{"type":"string","example":"A description of the product"},"balance":{"type":"number","example":100},"currency":{"type":"string","example":"GBP"}},"required":["sid","name","addr1","city","state","postcode","countryIso","registeredCountryIso","vatNumber","typeOfBusiness","productUseCase","website","productDescription","balance","currency"]},"OrganisationResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"$ref":"#/components/schemas/Organisation"}},"required":["success","result"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Invalid request"}},"required":["success","error"]},"SidResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"result":{"type":"object","properties":{"sid":{"type":"string","example":"EP12345678901234567890123456789012"}},"required":["sid"]}},"required":["success","result"]},"AssignedNumberV1_1":{"type":"object","properties":{"sid":{"type":"string","example":"AN12345678901234567890123456789012"},"numberSid":{"type":"string","example":"NB12345678901234567890123456789012"},"numberGroupSid":{"type":"string","example":"NG12345678901234567890123456789012"},"countryIso":{"type":"string","example":"GB"},"number":{"type":"string","example":"+447700900000"},"voiceEndpointSid":{"type":"string","example":"EP12345678901234567890123456789012"},"voiceEndpointName":{"type":"string","example":"Default Voice"},"smsEndpointSid":{"type":"string","example":"EP12345678901234567890123456789012"},"smsEndpointName":{"type":"string","example":"Default SMS"},"nextBillingDate":{"type":"string","format":"date-time","example":"2025-03-01T00:00:00.000Z"},"numberRental":{"type":"number","example":1.2}},"required":["sid","countryIso","number","numberRental"]},"Pagination":{"type":"object","properties":{"page":{"type":"number","description":"The current page number, starting at 1.","example":1},"perPage":{"type":"number","description":"The number of entries per page.","example":10},"pageCount":{"type":"number","minimum":1,"description":"The total number of pages.","example":6},"total":{"type":"number","minimum":0,"description":"The total number of entries.","example":52}},"required":["page","perPage","pageCount","total"]},"PaginationLinks":{"type":"object","properties":{"self":{"type":["string","null"],"format":"uri","description":"Link to the current page, or null when there are no results","example":"https://api.cloudnumbering.com/v1.1/numbers?page=2"},"next":{"type":["string","null"],"format":"uri","description":"Link to the next page, or null when there is no next page","example":"https://api.cloudnumbering.com/v1.1/numbers?page=3"},"prev":{"type":["string","null"],"format":"uri","description":"Link to the previous page, or null when there is no previous page","example":"https://api.cloudnumbering.com/v1.1/numbers?page=1"},"first":{"type":["string","null"],"format":"uri","description":"Link to the first page, or null when there are no results","example":"https://api.cloudnumbering.com/v1.1/numbers?page=1"},"last":{"type":["string","null"],"format":"uri","description":"Link to the last page, or null when there are no results","example":"https://api.cloudnumbering.com/v1.1/numbers?page=4"}},"required":["self","next","prev","first","last"]},"ResponseMeta":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"links":{"$ref":"#/components/schemas/PaginationLinks"}},"required":["pagination","links"]},"NumbersListResponseV1_1":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/AssignedNumberV1_1"}}},"required":["entries"]},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["success","result","meta"]},"AvailableNumberEntry":{"type":"object","properties":{"sid":{"type":"string","description":"The number SID to pass back when creating an order","example":"NB12345678901234567890123456789012"},"e164":{"type":"string","description":"The phone number in E.164 format","example":"+447700900000"},"countryIso":{"type":"string","description":"Two-letter ISO country code","example":"GB"}},"required":["sid","e164","countryIso"]},"AvailableNumbersListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/AvailableNumberEntry"}},"totalAvailable":{"type":"number","description":"Total count of matching available numbers","example":42}},"required":["entries","totalAvailable"]}},"required":["success","result"]},"ReconnectNumberBreakdown":{"type":"object","properties":{"assignedNumberSid":{"type":"string","example":"AN12345678901234567890123456789012"},"number":{"type":"string","example":"+447700900000"},"status":{"type":"string","enum":["eligible","not_eligible","pending","reconnected","failed"],"description":"Public reconnect status for this number.","example":"eligible"},"reconnectionCharge":{"type":"number","description":"One-off reconnection charge for this number.","example":5},"renewalCharge":{"type":"number","description":"Renewal charge due for this number.","example":10},"totalCharge":{"type":"number","description":"Total charge for this number.","example":15},"renewalPeriodCount":{"type":"number","description":"Number of renewal periods included in the renewal charge.","example":2},"previousNextBillingDate":{"type":"string","description":"Next billing date before reconnection.","example":"2026-05-01T00:00:00.000Z"},"projectedNextBillingDate":{"type":"string","description":"Expected next billing date after reconnection.","example":"2026-07-01T00:00:00.000Z"},"errorCode":{"type":"string","example":"not_disconnected"},"errorMessage":{"type":"string","example":"Number does not have status DISCONNECTED."}},"required":["assignedNumberSid"]},"StructuredError":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code.","example":"insufficient_funds"},"message":{"type":"string","description":"Human-readable error message.","example":"Insufficient funds."},"assignedNumberSid":{"type":"string","description":"Assigned number related to this error, when applicable.","example":"AN12345678901234567890123456789012"},"field":{"type":"string","description":"Request field related to this error, when applicable.","example":"numberSids"}},"required":["code","message"]},"NumberReconnectPreview":{"type":"object","properties":{"eligible":{"type":"boolean","example":true},"currency":{"type":"string","example":"GBP"},"totalCharge":{"type":"number","description":"Estimated total charge to reconnect the requested numbers.","example":15},"reconnectionCharge":{"type":"number","description":"Estimated one-off reconnection charge.","example":5},"renewalCharge":{"type":"number","description":"Estimated renewal charge due for reconnection.","example":10},"numbers":{"type":"array","items":{"$ref":"#/components/schemas/ReconnectNumberBreakdown"}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/StructuredError"}}}},"NumberReconnectPreviewResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"$ref":"#/components/schemas/NumberReconnectPreview"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/StructuredError"}},"error":{"type":"string"}},"required":["success"]},"NumberReconnectRequest":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed"],"description":"Public status for the reconnect request.","example":"completed"},"requestSid":{"type":"string","description":"Reconnect request SID. Use this with `GET /v1.1/numbers/reconnect/{requestSid}`.","example":"NR12345678901234567890123456789012"},"currency":{"type":"string","example":"GBP"},"totalCharged":{"type":"number","description":"Total amount charged for the reconnect request.","example":15},"reconnectionCharge":{"type":"number","description":"One-off reconnection charge included in the amount charged.","example":5},"renewalCharge":{"type":"number","description":"Renewal charge included in the amount charged.","example":10},"numbers":{"type":"array","items":{"$ref":"#/components/schemas/ReconnectNumberBreakdown"}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/StructuredError"}}},"required":["status"]},"NumberReconnectResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"$ref":"#/components/schemas/NumberReconnectRequest"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/StructuredError"}},"error":{"type":"string"}},"required":["success"]},"Endpoint":{"type":"object","properties":{"sid":{"type":"string","example":"EP12345678901234567890123456789012"},"type":{"type":"string","enum":["voice","sms"],"description":"The type of endpoint","example":"voice"},"description":{"type":"string","description":"A human-friendly label for the endpoint","example":"Default Voice"},"uri":{"type":"string","description":"The URI of the endpoint. The format of this defines where the endpoint will send traffic to.","example":"sip:%e164@127.0.0.1"},"createdAt":{"type":"string","description":"When the endpoint was created","example":"2026-04-02T09:00:00.000Z"},"updatedAt":{"type":"string","description":"When the endpoint was last updated","example":"2026-04-02T10:30:00.000Z"},"isDefault":{"type":"boolean","description":"Whether this is the default endpoint for its type","example":true},"isSecondary":{"type":"boolean","description":"Whether this endpoint is configured as the secondary voice endpoint","example":false},"assignedNumbersCount":{"type":"number","description":"Assigned numbers linked to this endpoint","example":12}},"required":["sid","type","description","uri","createdAt","isDefault"]},"EndpointsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/Endpoint"}}},"required":["entries"]}},"required":["success","result"]},"EndpointIPsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"string"}}},"required":["entries"]}},"required":["success","result"]},"OrderV1_1":{"type":"object","properties":{"sid":{"type":"string","example":"NOFEAD4A8A13B045DF98A35B54A99712F6"},"createdAt":{"type":"string","description":"When the order was created","example":"2026-04-02T09:00:00.000Z"},"totalCost":{"type":"number","description":"Total cost of the order","example":10},"monthlyCost":{"type":"number","description":"Recurring monthly cost of the order, excluding one-off charges","example":0.5},"numbersOrdered":{"type":"number","description":"How many numbers were purchased","example":3},"currency":{"type":"string","example":"GBP"},"rateCardSid":{"type":"string","description":"The rate card used for this order","example":"RC12345678901234567890123456789012"},"rateCardEntrySid":{"type":"string","description":"The rate card entry used for this order","example":"RE12345678901234567890123456789012"},"numberRentalLength":{"type":"number","description":"The number of months the numbers was purchased for","example":12}},"required":["sid","createdAt","totalCost","monthlyCost","numbersOrdered","currency","rateCardSid","rateCardEntrySid","numberRentalLength"]},"OrdersListResponseV1_1":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/OrderV1_1"}}},"required":["entries"]},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["success","result","meta"]},"OrderWithNumbersV1_1":{"allOf":[{"$ref":"#/components/schemas/OrderV1_1"},{"type":"object","properties":{"numbers":{"type":"array","items":{"type":"object","properties":{"sid":{"type":"string"},"number":{"type":"string"},"nextBillingDate":{"type":"string"},"lineRental":{"type":"number"}},"required":["sid","number","lineRental"]},"description":"Your new numbers","example":[{"sid":"ANFEAD4A8A13B045DF98A35B54A99712F6","number":"+447700900000","nextBillingDate":"1970-01-01T00:00:00.000Z","lineRental":1.2}]}},"required":["numbers"]}]},"OrderGetResponseV1_1":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"$ref":"#/components/schemas/OrderWithNumbersV1_1"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["success","result","meta"]},"OrderDetails":{"type":"object","properties":{"sid":{"type":"string","description":"The order SID","example":"NOFEAD4A8A13B045DF98A35B54A99712F6"},"numbers":{"type":"array","items":{"type":"object","properties":{"sid":{"type":"string"},"number":{"type":"string"}},"required":["sid","number"]},"description":"Your new numbers","example":[{"sid":"ANFEAD4A8A13B045DF98A35B54A99712F6","number":"+447700900000"}]}},"required":["sid","numbers"]},"OrdersCreateResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"$ref":"#/components/schemas/OrderDetails"}},"required":["success","result"]},"OrdersPreview":{"type":"object","properties":{"rentalCost":{"type":"number","description":"Total recurring rental cost across the order","example":30},"connectionCharge":{"type":"number","description":"Total one-off connection charge across the order, including any manual selection fee","example":7.5},"connectionChargePerNumber":{"type":"number","description":"Effective one-off connection charge per number for this preview, including any manual selection fee when numberSids is supplied","example":2.5},"totalCost":{"type":"number","description":"First-billing-period total cost (rental + connection)","example":37.5},"firstBillingDate":{"type":"string","description":"When the first billing period starts","example":"2026-04-02T09:00:00.000Z"},"nextBillingDate":{"type":"string","description":"When the next billing period starts","example":"2026-05-02T09:00:00.000Z"}},"required":["rentalCost","connectionCharge","connectionChargePerNumber","totalCost","firstBillingDate","nextBillingDate"]},"OrdersPreviewResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"$ref":"#/components/schemas/OrdersPreview"}},"required":["success","result"]},"CatalogueProduct":{"type":"object","properties":{"sid":{"type":"string","example":"RE12345678901234567890123456789012"},"description":{"type":"string","example":"A description of the product"},"connectionCharge":{"type":"number","description":"One-off connection charge for this product","example":0},"cost":{"type":"number","description":"Recurring rental cost for this product","example":10},"currency":{"type":"string","example":"GBP"},"terms":{"type":"string","enum":["MONTHLY","QUARTERLY","SIX_MONTHLY","ANNUALLY"],"description":"The terms of the product","example":"MONTHLY"},"highlights":{"type":"array","items":{"type":"string"},"description":"A list of highlights for the product","example":["Great product","Monthly billing"]}},"required":["sid","description","connectionCharge","cost","currency","terms","highlights"]},"CatalogueListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/CatalogueProduct"}}},"required":["entries"]}},"required":["success","result"]},"PortingOrderSummary":{"type":"object","properties":{"sid":{"type":"string"},"direction":{"type":"string","enum":["IN","OUT"]},"status":{"type":"string","enum":["IN_PROGRESS","CODE_READY","CODE_EXPIRED","FAILED","COMPLETED","CANCELLED"]},"codeType":{"type":"string","enum":["PAC","STAC"]},"e164":{"type":"string"},"assignedNumberSid":{"type":"string"},"placeholderAssignedNumberSid":{"type":"string"},"pacMasked":{"type":"string"},"requestedPortDate":{"type":"string"},"confirmedPortDate":{"type":"string"},"requestedAt":{"type":"string","format":"date-time"}},"required":["sid","direction","status","codeType","e164","requestedAt"]},"PortingOrderCreateError":{"type":"object","properties":{"assignedNumberSid":{"type":"string"},"e164":{"type":"string"},"clientReference":{"type":"string"},"idempotencyKey":{"type":"string"},"existingOrderSid":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]},"PortingOrdersCreateResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/PortingOrderSummary"}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/PortingOrderCreateError"}}},"required":["orders"]}},"required":["success","result"]},"PortingOrdersListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/PortingOrderSummary"}}},"required":["entries"]},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["success","result","meta"]},"PortingOrderDetails":{"allOf":[{"$ref":"#/components/schemas/PortingOrderSummary"},{"type":"object","properties":{"code":{"type":"string"},"codeExpiresAt":{"type":"string","format":"date-time"}}}]},"PortingOrderDetailsResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"$ref":"#/components/schemas/PortingOrderDetails"}},"required":["success","result"]}},"parameters":{}},"paths":{"/v1.1/oauth/token":{"post":{"tags":["Authentication"],"summary":"Create or refresh a token","description":"Issues OAuth2 tokens for the customer API. `v1.1` returns both camelCase and snake_case token fields for compatibility.","security":[],"operationId":"post_AuthTokenV1_1","parameters":[{"schema":{"type":"string","description":"OAuth2 client ID","example":"D5F5C2452715406BA932B1E325A8CEA2"},"required":true,"description":"OAuth2 client ID","name":"client_id","in":"query"},{"schema":{"type":"string","description":"OAuth2 client secret","example":"super-secret-client-credential"},"required":true,"description":"OAuth2 client secret","name":"client_secret","in":"query"},{"schema":{"type":"string","enum":["client_credentials","refresh_token"],"description":"OAuth2 grant type. Use `client_credentials` for a new access token or `refresh_token` to refresh an existing token."},"required":true,"description":"OAuth2 grant type. Use `client_credentials` for a new access token or `refresh_token` to refresh an existing token.","name":"grant_type","in":"query"},{"schema":{"type":"string","description":"Refresh token to exchange for a new access token. Required when `grant_type=refresh_token`.","example":"RT1234567890abcdef"},"required":false,"description":"Refresh token to exchange for a new access token. Required when `grant_type=refresh_token`.","name":"refresh_token","in":"query"}],"responses":{"200":{"description":"Your token","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenResponseV1_1"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenErrorResponse"}}}}}}},"/v1.1/organisation":{"get":{"tags":["Organisation"],"summary":"Get your organisation details","operationId":"get_OrganisationGetV1_1","responses":{"200":{"description":"Returns your organisation details","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganisationResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Organisation"],"summary":"Update your organisation details","description":"Updates editable organisation profile fields. Omitted fields are left unchanged. Balance and currency are read-only.","operationId":"put_OrganisationUpdateV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sid":{"type":"string","example":"OR12345678901234567890123456789012"},"name":{"type":"string","example":"My Organisation"},"tradingName":{"type":"string","example":"My Trading Name"},"addr1":{"type":"string","example":"123 Fake Street"},"addr2":{"type":"string","example":""},"city":{"type":"string","example":"Exeter"},"state":{"type":"string","example":"Devon"},"postcode":{"type":"string","example":"EX1 111"},"countryIso":{"type":"string","example":"GB"},"registeredCountryIso":{"type":"string","example":"GB"},"vatNumber":{"type":"string","example":"GB123456789"},"typeOfBusiness":{"type":"string","example":"Software"},"productUseCase":{"type":"string","example":"Internal"},"website":{"type":"string","example":"https://example.com"},"productDescription":{"type":"string","example":"A description of the product"}}}}}},"responses":{"200":{"description":"Returns your organisation SID","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SidResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/numbers":{"get":{"tags":["Numbers"],"summary":"List your numbers","description":"Lists your assigned numbers. When e164 is provided, the endpoint performs an exact lookup and returns at most one matching entry. When status is omitted, only IN_SERVICE numbers are returned.","operationId":"get_NumbersListV1_1","parameters":[{"schema":{"type":"string","minLength":1,"description":"Partial alias or customer reference match. Can be combined with `e164`."},"required":false,"description":"Partial alias or customer reference match. Can be combined with `e164`.","name":"alias","in":"query"},{"schema":{"type":"string","pattern":"^\\+[1-9][0-9]{1,14}$","description":"Exact E.164 number match. When provided, the endpoint returns at most one entry."},"required":false,"description":"Exact E.164 number match. When provided, the endpoint returns at most one entry.","name":"e164","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["IN_SERVICE","PORT_IN","PORT_OUT","DISCONNECTED"]},"description":"Number status filter. Repeat the parameter or use a comma-separated list. Defaults to `IN_SERVICE` when omitted."},"required":false,"description":"Number status filter. Repeat the parameter or use a comma-separated list. Defaults to `IN_SERVICE` when omitted.","name":"status","in":"query"},{"schema":{"type":["string","null"],"description":"Filter numbers whose next billing date is on or after this date. Can be combined with `e164`."},"required":false,"description":"Filter numbers whose next billing date is on or after this date. Can be combined with `e164`.","name":"nextBillingDateFrom","in":"query"},{"schema":{"type":["string","null"],"description":"Filter numbers whose next billing date is on or before this date. Can be combined with `e164`."},"required":false,"description":"Filter numbers whose next billing date is on or before this date. Can be combined with `e164`.","name":"nextBillingDateTo","in":"query"},{"schema":{"type":"number","minimum":1,"default":1,"description":"The page number to retrieve. Ignored when `e164` is provided."},"required":false,"description":"The page number to retrieve. Ignored when `e164` is provided.","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"The number of entries per page. Ignored when `e164` is provided."},"required":false,"description":"The number of entries per page. Ignored when `e164` is provided.","name":"perPage","in":"query"}],"responses":{"200":{"description":"Returns a list of numbers","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumbersListResponseV1_1"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/numbers/available":{"get":{"tags":["Numbers"],"summary":"List available numbers","description":"Browse the pool of numbers your organisation can purchase. The returned `sid` values can be echoed back as `numberSids` on `POST /v1.1/orders` (and `POST /v1.1/orders/preview`) to buy a specific selection.","operationId":"get_AvailableNumbersListV1_1","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":20,"description":"Optional E.164 wildcard pattern (use `*` as the wildcard, e.g. `*123*`)."},"required":false,"description":"Optional E.164 wildcard pattern (use `*` as the wildcard, e.g. `*123*`).","name":"pattern","in":"query"},{"schema":{"type":"number","minimum":1,"default":20,"description":"The maximum number of entries to return (default 20, clamped at 100)."},"required":false,"description":"The maximum number of entries to return (default 20, clamped at 100).","name":"limit","in":"query"}],"responses":{"200":{"description":"A list of available numbers","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableNumbersListResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/numbers/reconnect/preview":{"post":{"tags":["Numbers"],"summary":"Preview number reconnection charges","description":"Returns the estimated cost and eligibility for reconnecting one or more numbers with status `DISCONNECTED`. The final charge is confirmed when you reconnect.","operationId":"post_NumberReconnectPreviewV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"numberSids":{"type":"array","items":{"type":"string","pattern":"^AN[A-Z0-9]{32}$"},"minItems":1,"maxItems":100,"description":"Number SIDs to preview. Each number must currently have status `DISCONNECTED`.","example":["AN12345678901234567890123456789012"]}},"required":["numberSids"]}}}},"responses":{"200":{"description":"The previewed reconnection cost breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectPreviewResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Number reconnection is not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}},"503":{"description":"Number reconnection is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}}}}},"/v1.1/numbers/reconnect":{"post":{"tags":["Numbers"],"summary":"Reconnect numbers","description":"Reconnects one or more numbers with status `DISCONNECTED`. Charges may apply; use `POST /v1.1/numbers/reconnect/preview` to preview the cost before reconnecting. The request succeeds or fails as a whole and supports up to 100 numbers.","operationId":"post_NumberReconnectBulkV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"numberSids":{"type":"array","items":{"type":"string","pattern":"^AN[A-Z0-9]{32}$"},"minItems":1,"maxItems":100,"description":"Number SIDs to reconnect. Each number must currently have status `DISCONNECTED`.","example":["AN12345678901234567890123456789012"]},"idempotencyKey":{"type":"string","format":"uuid","description":"Optional UUID used to make retries for this reconnection request idempotent.","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["numberSids"]}}}},"responses":{"200":{"description":"Reconnection completed or is pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Number reconnection is not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}},"503":{"description":"Number reconnection is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}}}}},"/v1.1/numbers/reconnect/{requestSid}":{"get":{"tags":["Numbers"],"summary":"Get reconnection request status","description":"Returns the status and charge breakdown for a reconnection request belonging to your organisation, using the `requestSid` returned by `POST /v1.1/numbers/reconnect`.","operationId":"get_NumberReconnectRequestGetV1_1","parameters":[{"schema":{"type":"string","pattern":"^NR[A-Z0-9]{32}$"},"required":true,"name":"requestSid","in":"path"}],"responses":{"200":{"description":"Reconnection request status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Number reconnection is not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}},"404":{"description":"Reconnection request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}},"503":{"description":"Number reconnection is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberReconnectResponse"}}}}}}},"/v1.1/numbers/{sid}/endpoints":{"post":{"tags":["Numbers"],"summary":"Assign endpoints to a number","description":"Assigns voice and/or SMS endpoints to an existing number and updates its customer reference. At least one endpoint SID must be provided.","operationId":"post_NumberSetEndpointsV1_1","parameters":[{"schema":{"type":"string","description":"The SID of the number to assign endpoints to"},"required":true,"description":"The SID of the number to assign endpoints to","name":"sid","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"voiceEndpointSid":{"type":"string","description":"The SID of the voice endpoint to assign"},"smsEndpointSid":{"type":"string","description":"The SID of the SMS endpoint to assign"},"reference":{"type":"string","description":"A custom reference or alias for the number"}},"required":["reference"]}}}},"responses":{"200":{"description":"The SID of the updated assigned number","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SidResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/numbers/{sid}":{"delete":{"tags":["Numbers"],"summary":"Disconnect a number","description":"Disconnects a number from your account. Disconnected numbers stop service and may be eligible for reconnection.","operationId":"delete_NumberDisconnectV1_1","parameters":[{"schema":{"type":"string","pattern":"^AN[A-Z0-9]{32}$","description":"The SID of the number to disconnect"},"required":true,"description":"The SID of the number to disconnect","name":"sid","in":"path"}],"responses":{"204":{"description":"Number disconnected successfully","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Number not found","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/endpoints":{"get":{"tags":["Endpoints"],"summary":"List your endpoints","description":"Returns the active endpoints configured for your organisation, including assignment counts and default and secondary flags.","operationId":"get_EndpointsListV1_1","responses":{"200":{"description":"A list of active endpoints for your organisation","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointsListResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Endpoints"],"summary":"Create an endpoint","description":"Creates a new voice or SMS endpoint for your organisation. Voice endpoints must use `sip:` URIs. SMS endpoints can use HTTPS callbacks or `mailto:` URIs.","operationId":"post_EndpointsCreateV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"A description of the endpoint"},"endpointType":{"type":"string","enum":["voice","sms"],"description":"The type of endpoint to create"},"uri":{"type":"string","description":"The URI of the endpoint.\n\nFor Voice endpoints, this must start with `sip:` and supports variables: `%e164`, `%raw` and `%national` for the E.164, raw and national number formats respectively. e.g. `sip:%e164@127.0.0.1:5060`\n\nFor SMS endpoints, this can be a HTTPS or Email URI. e.g. `https://example.com/callback` or `mailto:youremail@example.com`\n        ","example":"sip:%e164@127.0.0.1:5060"},"isDefault":{"type":"boolean","description":"If true, this becomes the default for this endpoint type and replaces any existing default. Existing numbers with explicit endpoints are not reassigned."},"isSecondary":{"type":"boolean","description":"Whether this endpoint is the secondary for the endpoint type"}},"required":["description","endpointType","uri"]}}}},"responses":{"200":{"description":"The SID of the created endpoint","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SidResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/endpoints/{sid}":{"put":{"tags":["Endpoints"],"summary":"Update an endpoint","description":"Updates the URI, description, or default status for an existing endpoint.","operationId":"put_EndpointsUpdateV1_1","parameters":[{"schema":{"type":"string","description":"The SID of the endpoint to update"},"required":true,"description":"The SID of the endpoint to update","name":"sid","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"A description of the endpoint"},"isDefault":{"type":"boolean","description":"If true, this becomes the default for this endpoint type and replaces any existing default. Existing numbers with explicit endpoints are not reassigned."},"uri":{"type":"string","description":"The URI of the endpoint.\n\nFor Voice endpoints, this must start with `sip:` and supports variables: `%e164`, `%raw` and `%national` for the E.164, raw and national number formats respectively. e.g. `sip:%e164@127.0.0.1:5060`\n\nFor SMS endpoints, this can be a HTTPS or Email URI. e.g. `https://example.com/callback` or `mailto:youremail@example.com`\n        ","example":"sip:%e164@127.0.0.1:5060"}},"required":["description","uri"]}}}},"responses":{"200":{"description":"Your updated endpoint SID","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SidResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Endpoints"],"summary":"Delete an endpoint","description":"Deactivates an endpoint. Set `unlinkAssignedNumbers=true` to remove existing number assignments as part of the same request.","operationId":"delete_EndpointsDeleteV1_1","parameters":[{"schema":{"type":"string","description":"The SID of the endpoint to deactivate"},"required":true,"description":"The SID of the endpoint to deactivate","name":"sid","in":"path"},{"schema":{"type":["boolean","null"],"description":"When true, unassign all numbers from this endpoint as part of deactivation (defaults to false)"},"required":false,"description":"When true, unassign all numbers from this endpoint as part of deactivation (defaults to false)","name":"unlinkAssignedNumbers","in":"query"}],"responses":{"200":{"description":"The SID of the deactivated endpoint","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SidResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/endpoints/{endpointType}/ips":{"get":{"tags":["Endpoints"],"summary":"List allowed source IPs","description":"Lists the source IP addresses allowed to initiate inbound voice traffic for your organisation.","operationId":"get_EndpointIPsListV1_1","parameters":[{"schema":{"type":"string","description":"Endpoint type"},"required":true,"description":"Endpoint type","name":"endpointType","in":"path"}],"responses":{"200":{"description":"List of allowed IPs for the endpoint type","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointIPsListResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Endpoints"],"summary":"Add an allowed source IP","description":"Adds a source IP address to the allow list used for inbound voice traffic. This operation is idempotent.","operationId":"post_EndpointIPsCreateV1_1","parameters":[{"schema":{"type":"string","enum":["voice"],"description":"The type of endpoint to create the IP for, currently this is always 'voice'","example":"voice"},"required":true,"description":"The type of endpoint to create the IP for, currently this is always 'voice'","name":"endpointType","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","description":"The IP address to add to the allowed list","example":"10.0.0.1"}},"required":["ip"]}}}},"responses":{"200":{"description":"The updated allow list for the endpoint type","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointIPsListResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/endpoints/{endpointType}/ips/{ip}":{"delete":{"tags":["Endpoints"],"summary":"Remove an allowed source IP","description":"Removes a source IP address from the allow list used for inbound voice traffic. This operation is idempotent.","operationId":"delete_EndpointIPsDeleteV1_1","parameters":[{"schema":{"type":"string","enum":["voice"],"description":"The type of endpoint to delete the IP for, currently this is always 'voice'","example":"voice"},"required":true,"description":"The type of endpoint to delete the IP for, currently this is always 'voice'","name":"endpointType","in":"path"},{"schema":{"type":"string","description":"The IP address to remove from the allowed list","example":"10.0.0.1"},"required":true,"name":"ip","in":"path"}],"responses":{"200":{"description":"The updated allow list for the endpoint type","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointIPsListResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/orders":{"get":{"tags":["Order"],"summary":"List orders","description":"Lists the number orders placed by your organisation.","operationId":"get_OrdersListV1_1","parameters":[{"schema":{"type":"number","minimum":1,"default":1,"description":"The page number to retrieve"},"required":false,"description":"The page number to retrieve","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"The number of entries per page"},"required":false,"description":"The number of entries per page","name":"perPage","in":"query"}],"responses":{"200":{"description":"Returns a list of orders","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersListResponseV1_1"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Order"],"summary":"Create an Order","description":"Creates a new number order using a catalogue rate-card entry. Pass `numberSids` to buy a specific selection returned from `GET /v1.1/numbers/available`; omit it to be randomly allocated `amount` numbers from the pool.","operationId":"post_OrdersCreateV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["numbers"]},"amount":{"type":"number","description":"How many numbers to purchase","example":3},"rateCardEntrySid":{"type":"string","description":"The rate card entry used for this order","example":"RE12345678901234567890123456789012"},"numberSids":{"type":"array","items":{"type":"string"},"description":"Optional list of specific number SIDs (returned by `GET /v1.1/numbers/available`) to purchase. When provided, `amount` is derived from this list's length. Manual selection incurs an additional per-number connection charge.","example":["NB12345678901234567890123456789012","NB12345678901234567890123456789013"]}},"required":["type","rateCardEntrySid"],"description":"Number order"}}}},"responses":{"200":{"description":"The created order and assigned numbers","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersCreateResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/orders/{sid}":{"get":{"tags":["Order"],"summary":"Get an order","description":"Returns a single number order together with the assigned numbers created by that order.","operationId":"get_OrdersGetV1_1","parameters":[{"schema":{"type":"string","description":"The SID of the order","example":"NOFEAD4A8A13B045DF98A35B54A99712F6"},"required":true,"description":"The SID of the order","name":"sid","in":"path"},{"schema":{"type":"number","minimum":1,"default":1,"description":"The page of assigned numbers within this order to retrieve"},"required":false,"description":"The page of assigned numbers within this order to retrieve","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"How many assigned numbers from this order to return per page"},"required":false,"description":"How many assigned numbers from this order to return per page","name":"perPage","in":"query"}],"responses":{"200":{"description":"Order details and the assigned numbers created by that order","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderGetResponseV1_1"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/orders/preview":{"post":{"tags":["Order"],"summary":"Preview order cost","description":"Returns the cost of a number order without placing the order or reserving numbers. Accepts the same body as `POST /v1.1/orders`, including the manual selection fee when `numberSids` is supplied.","operationId":"post_OrdersPreviewV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["numbers"]},"amount":{"type":"number","description":"How many numbers to price","example":3},"rateCardEntrySid":{"type":"string","description":"The rate card entry to price against","example":"RE12345678901234567890123456789012"},"numberSids":{"type":"array","items":{"type":"string"},"description":"Optional list of specific number SIDs (returned by `GET /v1.1/numbers/available`) to price. When provided, `amount` is derived from this list's length and the preview includes the per-number manual selection fee.","example":["NB12345678901234567890123456789012","NB12345678901234567890123456789013"]}},"required":["type","rateCardEntrySid"],"description":"Number order preview"}}}},"responses":{"200":{"description":"The previewed cost breakdown","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersPreviewResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/catalogue":{"get":{"tags":["Catalogue"],"summary":"List the available catalogue","description":"Lists the rate-card products currently available for number purchases by your organisation.","operationId":"get_CatalogueListV1_1","responses":{"200":{"description":"Returns a list of available products","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogueListResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/porting/in":{"post":{"tags":["Porting"],"summary":"Port numbers in","description":"Creates PAC-based port-in requests for one or more numbers. The response can contain both created/reused orders and per-number validation errors.","operationId":"post_PortingInCreateV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"e164":{"type":"string","pattern":"^\\+[1-9][0-9]{6,14}$","description":"The number to port in, in E.164 format.","example":"+447700900000"},"pac":{"type":"string","pattern":"^[A-Za-z0-9]{6,12}$","description":"The PAC supplied by the losing provider.","example":"ABC123"},"requestedPortDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Requested port date as a London local date, YYYY-MM-DD.","example":"2026-06-18"},"rateCardEntrySid":{"type":"string","pattern":"^RE[A-Z0-9]{32}$","description":"Rate card entry SID used to purchase the donor number.","example":"RE12345678901234567890123456789012"},"idempotencyKey":{"type":"string","format":"uuid","description":"Optional UUID used to make retries for this entry idempotent.","example":"550e8400-e29b-41d4-a716-446655440000"},"clientReference":{"type":"string","maxLength":128,"description":"Optional caller reference echoed in per-entry responses and errors.","example":"spreadsheet-row-37"}},"required":["e164","pac","requestedPortDate","rateCardEntrySid"]},"minItems":1,"maxItems":100,"description":"Numbers to port in"}},"required":["entries"]}}}},"responses":{"200":{"description":"Created or reused port-in orders and any per-number validation errors","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortingOrdersCreateResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Port-in is not enabled for this organisation","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/porting/out":{"post":{"tags":["Porting"],"summary":"Request PAC","description":"Creates PAC-based port-out requests for one or more assigned numbers. The response can contain both created orders and per-number validation errors.","operationId":"post_PortingOutCreateV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignedNumberSids":{"type":"array","items":{"type":"string","pattern":"^AN[A-Z0-9]{32}$"},"minItems":1,"maxItems":100,"description":"Assigned number SIDs to port out"},"codeType":{"type":"string","enum":["PAC","pac"],"description":"Request a PAC code"}},"required":["assignedNumberSids","codeType"]}}}},"responses":{"200":{"description":"Created port-out orders and any per-number validation errors","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortingOrdersCreateResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/porting/orders":{"get":{"tags":["Porting"],"summary":"List porting orders","description":"Lists porting orders for your organisation. Supports paginated filtering by assigned number, E.164, or port order SID.","operationId":"get_PortingOrdersListV1_1","parameters":[{"schema":{"type":"number","minimum":1,"default":1,"description":"The page number to retrieve"},"required":false,"description":"The page number to retrieve","name":"page","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"The number of entries per page"},"required":false,"description":"The number of entries per page","name":"perPage","in":"query"},{"schema":{"type":"string","pattern":"^PO[A-Z0-9]{32}$","description":"Exact port order SID lookup. When provided, the result contains at most one entry."},"required":false,"description":"Exact port order SID lookup. When provided, the result contains at most one entry.","name":"sid","in":"query"},{"schema":{"type":"string","pattern":"^AN[A-Z0-9]{32}$","description":"Filter port orders for a specific assigned number SID."},"required":false,"description":"Filter port orders for a specific assigned number SID.","name":"assignedNumberSid","in":"query"},{"schema":{"type":"string","description":"Filter port orders for a specific E.164 number."},"required":false,"description":"Filter port orders for a specific E.164 number.","name":"e164","in":"query"},{"schema":{"type":["boolean","null"],"description":"When true, only return active port orders."},"required":false,"description":"When true, only return active port orders.","name":"activeOnly","in":"query"}],"responses":{"200":{"description":"Returns a list of port orders","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortingOrdersListResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Port order not found","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/porting/orders/{sid}":{"get":{"tags":["Porting"],"summary":"Get a port order","description":"Returns detailed information for a single port order, including any generated code and expiry time when available.","operationId":"get_PortingOrderGetV1_1","parameters":[{"schema":{"type":"string","pattern":"^PO[A-Z0-9]{32}$","description":"The port order SID"},"required":true,"description":"The port order SID","name":"sid","in":"path"}],"responses":{"200":{"description":"Port order","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortingOrderDetailsResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"You are not allowed to access this port order","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Port order not found","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The port order exists but is not yet ready for the requested data","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1.1/sms":{"post":{"tags":["SMS"],"summary":"Send an SMS","description":"Sends an outbound SMS from one of your assigned numbers. The `from` number must belong to your organisation.","operationId":"post_SMSSendV1_1","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"The number to send the SMS to"},"from":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"The number to send the SMS from"},"content":{"type":"string","description":"The content of the SMS"},"dlrUrl":{"type":"string","description":"The URL to send the delivery receipt to"}},"required":["to","from","content"]}}}},"responses":{"200":{"description":"Returns the SID of your SMS","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SidResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The `from` number was not found or does not belong to your organisation","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The outbound messaging service is temporarily unavailable","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid","description":"The request ID for reference"},"required":true,"description":"The request ID for reference"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}