openapi: '3.0.3' info: title: Numbers | Sinch description: >- An API service for getting, listing and managing Sinch phone numbers. version: '1.0' contact: name: Support url: www.sinch.com email: Support@sinch.com license: name: MIT url: "https://www.sinch.com/toc" servers: - url: https://numbers.api.sinch.com description: Global API security: - Basic: [] - OAuth2.0: [] tags: - name: Available Number description: You can use the Available Number API to search for available numbers or activate an available number. - name: Active Number description: You can use the Active Number API to manage numbers you own. Release numbers from projects or list all numbers assigned to a project. - name: Available Regions description: You can use the Available Regions API to list all of the regions that have numbers assigned to a project. - name: Numbers Callbacks description: |- You can set up callback URLs to receive event notifications when your numbers are updated. When delivering events the order is not guaranteed (for example, a failed event scheduled for retry will not block other events that were queued). The client's callback handler must implement the state machine that can decide what to do with _unexpected_ events, for example, "old" events or invalid state transitions. In these cases the handler could use the API to GET the latest state for the resource. The callback handler is expected to "ingest" the event and respond with 200 OK. The domain-specific business logic and processes should be executed outside of the callback request, as internal asynchronous jobs. To use callbacks, add the following IP addresses to your allowlist: - 54.76.19.159 - 54.78.194.39 - 54.155.83.128 ### Secure Webhook Endpoints with HMAC Implementing HMAC (Hash-based Message Authentication Code) on your webhook endpoints will ensure the integrity of data, preventing tampering during transmission. An HMAC used in webhooks is a common approach in the industry and in a nutshell it is just special code that can be used to check if a message hasn’t been tempered with during the transmission. We recommend to configure an HMAC secret for your project using the [callback configuration](/docs/numbers/api-reference/numbers/tag/Numbers-Callbacks/#tag/Numbers-Callbacks/operation/UpdateCallbackConfiguration). Then, when sending the number events, the HTTP POST requests will include the header `X-Sinch-Signature` with the computed HMAC. **NOTE:** The HMAC secret is configured per project; if you are using the Numbers API with multiple projects, make sure you configure the HMAC secret in each project, and fetch it for either imported or purchased numbers from the dedicated endpoints. ### HMAC verification We recommend to verify the HMAC code received with every event in your event handler. When receiving a new event on your endpoint URL, compute the HMAC of the payload using the secret (configured [here](/docs/numbers/api-reference/numbers/tag/Numbers-Callbacks/#tag/Numbers-Callbacks/operation/UpdateCallbackConfiguration)) and compare it with one received in the `X-Sinch-Signature` header. **NOTE:** Compute the HMAC on the plain text value before parsing the JSON payload. x-explorer-enabled: false x-samples-languages: - curl - java - csharp - node - php x-webhooks: EventsCallback: post: tags: - Numbers Callbacks summary: Event notification description: A notification of an event sent to your configured callback URL. operationId: ImportedNumberService_EventsCallback requestBody: content: application/json: schema: $ref: '#/components/schemas/CallbackPayload' responses: default: description: 200 OK paths: '/v1/projects/{projectId}/availableNumbers/{phoneNumber}:rent': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/phoneNumber' post: summary: Activate a new phone number description: |- Activate a phone number to use with SMS products, Voice products, or both. You'll use `smsConfiguration` to setup your number for SMS and `voiceConfiguration` for Voice. To setup for both, add both objects. See the dropdown menu (just under language selection) for code samples. Note: You cannot add both objects if you only need to configure one object. For example, if you only need to configure `smsConfiguration` for SMS messaging, do not add the `voiceConfiguration` object or it will result in an error. operationId: NumberService_RentNumber requestBody: $ref: '#/components/requestBodies/RentNumberRequest' responses: '200': $ref: '#/components/responses/ActiveNumberResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' tags: - Available Number /v1/projects/{projectId}/availableNumbers:rentAny: parameters: - $ref: "#/components/parameters/projectId" post: tags: - Available Number summary: Rent any number that matches the criteria description: 'Activates a phone number that matches the search criteria provided in the request. Currently the rentAny operation works only for US LOCAL numbers' operationId: NumberService_RentAnyNumber requestBody: description: The request to search and rent a number that matches the criteria. content: application/json: schema: $ref: '#/components/schemas/RentAnyNumberRequest' examples: activateSMSNumber: $ref: '#/components/examples/SearchActivateSMSNumber' required: true responses: '200': description: A successful response, or an error. headers: {} content: application/json: schema: $ref: '#/components/schemas/ActiveNumberResponse' '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' deprecated: false '/v1/projects/{projectId}/activeNumbers': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/regionCode' - $ref: '#/components/parameters/numberPattern.pattern' - $ref: '#/components/parameters/numberPattern.searchPattern' - $ref: '#/components/parameters/type' - $ref: '#/components/parameters/capability' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/pageToken' - $ref: '#/components/parameters/orderBy' get: summary: Lists active numbers for a project description: Lists all active numbers for a project. operationId: NumberService_ListActiveNumbers responses: '200': $ref: '#/components/responses/ListActiveNumbersResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' tags: - Active Number '/v1/projects/{projectId}/activeNumbers/{phoneNumber}': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/phoneNumber' patch: summary: Update an active phone number description: |- Update an active phone number. You can perform the following updates: * Update the name that displays for a customer by modifying the `displayName` parameter. * Unlink the number from an SMS service or campaign by updating the `smsConfiguration` configuration object. To unlink a number, submit the request with an empty string (`””`) in the service plan ID or campaign ID fields. * Before linking a number to a new service or campaign, it must be unlinked from any existing service or campaign. Then, link the number to a new SMS service or campaign by updating the service plan ID or campaign ID with the new desired value. * Update the Voice app to which the number is assigned by using the voiceConfiguration object. You can update both SMS and Voice in the same object by including both configuration objects. If you only need to update either Voice or SMS, simply omit the other object. If you pass an empty configuration object, the request will fail. operationId: NumberService_UpdateActiveNumber requestBody: $ref: '#/components/requestBodies/ActiveNumberRequest' responses: '200': $ref: '#/components/responses/ActiveNumberResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' tags: - Active Number get: summary: Retrieve an active phone number operationId: NumberService_GetActiveNumber responses: '200': $ref: '#/components/responses/ActiveNumberResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' tags: - Active Number '/v1/projects/{projectId}/activeNumbers/{phoneNumber}:release': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/phoneNumber' post: summary: Release an active number from the project description: With this endpoint, you can cancel your subscription for a specific phone number. operationId: NumberService_ReleaseNumber responses: '200': $ref: '#/components/responses/ActiveNumberResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' tags: - Active Number '/v1/projects/{projectId}/availableNumbers': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/numberPattern.pattern' - $ref: '#/components/parameters/numberPattern.searchPattern' - $ref: '#/components/parameters/regionCode' - $ref: '#/components/parameters/type' - $ref: '#/components/parameters/capabilities' - name: size description: Optional. The maximum number of items to return. in: query required: false schema: type: integer format: int32 example: 3 get: summary: Search for available phone numbers description: |- Search for available phone numbers that are available for you to activate. You can filter by any property on the available number resource. When searching, indicate the `capability` of the number in the array as `SMS` and/or `VOICE`. To search for a number capable of both, list both `SMS` and `VOICE`. operationId: NumberService_ListAvailableNumbers responses: '200': $ref: '#/components/responses/ListAvailableNumbersResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' tags: - Available Number '/v1/projects/{projectId}/availableNumbers/{phoneNumber}': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/phoneNumber' get: summary: Search for a specific phone number description: This endpoint allows you to enter a specific phone number to check if it's available for use. A 200 response will return the number's capability, setup costs, monthly costs and if supporting documentation is required. operationId: NumberService_GetAvailableNumber responses: '200': $ref: '#/components/responses/AvailableNumberResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) tags: - Available Number '/v1/projects/{projectId}/availableRegions': parameters: - $ref: '#/components/parameters/projectId' - name: types description: >- Only return regions for which numbers are provided with the given types v1: `MOBILE`, `LOCAL` or `TOLL_FREE`. - NUMBER_TYPE_UNSPECIFIED: Null value - MOBILE: Numbers that belong to a specific range. - LOCAL: Numbers that are assigned to a specific geographic region. - TOLL_FREE: Number that are free of charge for the calling party but billed for all arriving calls. in: query required: false schema: type: array items: type: string enum: - NUMBER_TYPE_UNSPECIFIED - MOBILE - LOCAL - TOLL_FREE get: summary: List available regions description: Lists all regions for numbers provided for the project ID. operationId: NumberService_ListAvailableRegions responses: '200': $ref: '#/components/responses/ListAvailableRegionsResponse' description: A successful response, or an [error](/docs/numbers/api-reference/error-codes/status-codes/) '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' tags: - Available Regions /v1/projects/{projectId}/callbackConfiguration: get: summary: Get callbacks configuration description: Returns the callbacks configuration for the specified project operationId: GetCallbackConfiguration responses: '200': description: Callbacks configuration content: application/json: schema: $ref: "#/components/schemas/CallbackConfiguration" '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' parameters: - $ref: "#/components/parameters/projectId" tags: - Numbers Callbacks patch: summary: Update callback configuration description: Updates the callbacks configuration for the specified project operationId: UpdateCallbackConfiguration requestBody: description: The callback configuration details to be updated. content: application/json: schema: $ref: '#/components/schemas/CallbackConfigurationUpdate' responses: '200': description: Callback configuration content: application/json: schema: $ref: '#/components/schemas/CallbackConfiguration' '400': description: 400 Invalid Argument error content: application/json: schema: $ref: '#/components/schemas/InvalidArgument' '404': description: 404 Not Found error content: application/json: schema: $ref: '#/components/schemas/NotFound' '500': description: 500 Internal Server error content: application/json: schema: $ref: '#/components/schemas/InternalError' parameters: - $ref: "#/components/parameters/projectId" tags: - Numbers Callbacks components: parameters: projectId: name: projectId description: Found on your [Sinch Customer Dashboard](https://dashboard.sinch.com/settings/project-management). Settings > Projects. in: path required: true schema: type: string example: YOUR_projectId phoneNumber: name: phoneNumber description: |- Output only. The phone number in E.164 format with leading `+`. in: path required: true schema: type: string example: '+12025550134' default: "YOUR_selected_phoneNumber_from_search" numberPattern.pattern: name: numberPattern.pattern description: Sequence of digits to search for. If you prefer or need certain digits in sequential order, you can enter the sequence of numbers here. For example, `2020`. in: query required: false schema: type: string numberPattern.searchPattern: name: numberPattern.searchPattern description: Search pattern to apply. The options are, `START`, `CONTAINS`, and `END`. in: query required: false schema: type: string enum: - START - CONTAINS - END x-enumDescriptions: START: Numbers that begin with the `numberPattern.pattern` entered. Often used to search for a specific area code. When using `START`, a plus sign (+) must be included and URL encoded, so `%2B`. For example, to search for area code 206 in the US, you would enter, `%2b1206`. CONTAINS: The number pattern entered is contained somewhere in the number, the location being undefined. END: The number ends with the number pattern entered. regionCode: name: regionCode description: "Region code to filter by. ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE." in: query required: true schema: type: string example: US type: name: type description: Number type to filter by. Options include, `MOBILE`, `LOCAL` or `TOLL_FREE`. in: query required: true schema: type: string enum: - MOBILE - LOCAL - TOLL_FREE x-enumDescriptions: MOBILE: Numbers that belong to a specific range. LOCAL: Numbers that are assigned to a specific geographic region. TOLL_FREE: Number that are free of charge for the calling party but billed for all arriving calls. example: LOCAL capabilities: name: capabilities description: Number capabilities to filter by SMS and/or VOICE. in: query required: false schema: type: array items: type: string x-enumDescriptions: SMS: The SMS product can use the number VOICE: The Voice product can use the number capability: name: capability description: Number capabilities to filter by SMS and/or VOICE. in: query required: false schema: type: array items: type: string x-enumDescriptions: SMS: The SMS product can use the number. VOICE: The Voice product can use the number. pageSize: name: pageSize description: The maximum number of items to return. in: query required: false schema: type: integer format: int32 pageToken: name: pageToken description: The next page token value returned from a previous List request, if any. in: query required: false schema: type: string orderBy: name: orderBy description: Supported fields for ordering by `phoneNumber` or `displayName`. in: query required: false schema: type: string examples: SearchActivateSMSNumber: summary: Search and activate a number that matches criteria and sets the SMS configuration value: regionCode: US type: LOCAL capabilities: ["SMS"] numberPattern: pattern: "+1208" searchPattern: START smsConfiguration: servicePlanId: YOUR_SMS_servicePlanId campaignId: YOUR_campaignId_from_TCR callbackUrl: https://www.your-callback-server.com/callback activateSMSNumberReq: summary: Activate number with SMS configuration value: smsConfiguration: servicePlanId: "YOUR_SMS_servicePlanId" campaignId: "YOUR_campaignId_from_TCR" callbackUrl: https://www.your-callback-server.com/callback activateSMSNumberRes: summary: Response for activing a number with SMS configuration value: phoneNumber: "+12025550134" projectId: "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a" displayName: "MyPhoneNumber" regionCode: "US" type: "MOBILE" capability: - SMS money: currencyCode: "USD" amount: "2.00" paymentIntervalMonths: 0 nextChargeDate: "2024-08-24T14:15:22Z" expireAt: "2024-09-24T14:15:22Z" smsConfiguration: servicePlanId: "YOUR_service_plan_id" scheduledProvisioning: servicePlanId: "YOUR_service_plan_id" status: WAITING lastUpdatedTime: "2024-08-04T14:15:22Z" campaignId: "YOUR_campaign_id" campaignId: "YOUR_campaign_id" activateBothSMSandVoiceNumberReq: summary: Activate number with SMS and Voice configuration value: smsConfiguration: servicePlanId: "YOUR_SMS_servicePlanId" voiceConfiguration: type: RTC appId: "YOUR_Voice_appId" callbackUrl: https://www.your-callback-server.com/callback activateBothSMSandVoiceNumberRes: summary: Response for activing a number with both SMS and Voice configuration value: phoneNumber: "+12025550134" projectId: "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a" displayName: "MyPhoneNumber" regionCode: "US" type: "MOBILE" capability: - SMS - VOICE money: currencyCode: "USD" amount: "2.00" paymentIntervalMonths: 0 nextChargeDate: "2024-08-24T14:15:22Z" expireAt: "2024-09-24T14:15:22Z" smsConfiguration: servicePlanId: "YOUR_service_plan_id" scheduledProvisioning: servicePlanId: "" status: WAITING lastUpdatedTime: "2024-08-04T14:15:22Z" campaignId: "YOUR_campaign_id" campaignId: "YOUR_campaign_id" voiceConfiguration: type: RTC lastUpdatedTime: "2024-09-24T14:15:22Z" scheduledVoiceProvisioning: type: RTC lastUpdatedTime: "2024-09-24T14:15:22Z" status: WAITING appId: "YOUR_app_id" appId: "YOUR_app_id" activateVoiceNumberReq: summary: Activate number with Voice configuration value: voiceConfiguration: type: RTC appId: "YOUR_app_id" callbackUrl: https://www.your-callback-server.com/callback activateVoiceNumberRes: summary: Response for activing a number with Voice configuration value: phoneNumber: "+12025550134" projectId: "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a" displayName: "MyPhoneNumber" regionCode: "US" type: "MOBILE" capability: - VOICE money: currencyCode: "USD" amount: "2.00" paymentIntervalMonths: 0 nextChargeDate: "2024-08-24T14:15:22Z" expireAt: "2024-09-24T14:15:22Z" voiceConfiguration: type: RTC lastUpdatedTime: "2024-09-24T14:15:22Z" scheduledVoiceProvisioning: type: RTC lastUpdatedTime: "2024-09-24T14:15:22Z" status: WAITING appId: "YOUR_app_id" appId: "YOUR_app_id" activateESTNumberReq: summary: Activate number with Elastic SIP Trunking configuration value: voiceConfiguration: type: EST trunkId: "YOUR_trunk_id" callbackUrl: https://www.your-callback-server.com/callback activateESTNumberRes: summary: Response for activing a number with Elastic SIP Trunking configuration value: phoneNumber: "+12025550134" projectId: "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a" displayName: "MyPhoneNumber" regionCode: "US" type: "LOCAL" capability: - VOICE money: currencyCode: "USD" amount: "2.00" paymentIntervalMonths: 0 nextChargeDate: "2024-08-24T14:15:22Z" expireAt: "2024-09-24T14:15:22Z" voiceConfiguration: type: EST lastUpdatedTime: "2024-09-24T14:15:22Z" scheduledVoiceProvisioning: type: EST lastUpdatedTime: "2024-09-24T14:15:22Z" status: WAITING trunkId: "YOUR_trunk_id" trunkId: "YOUR_trunk_id" activateFaxNumberReq: summary: Activate number with Fax configuration value: voiceConfiguration: type: FAX serviceId: "YOUR_service_id" callbackUrl: https://www.your-callback-server.com/callback activateFaxNumberRes: summary: Response for activing a number with Fax configuration value: phoneNumber: "+12025550134" projectId: "51bc3f40-f266-4ca8-8938-a1ed0ff32b9a" displayName: "MyPhoneNumber" regionCode: "US" type: "LOCAL" capability: - VOICE money: currencyCode: "USD" amount: "2.00" paymentIntervalMonths: 0 nextChargeDate: "2024-08-24T14:15:22Z" expireAt: "2024-09-24T14:15:22Z" voiceConfiguration: type: FAX lastUpdatedTime: "2024-09-24T14:15:22Z" scheduledVoiceProvisioning: type: FAX lastUpdatedTime: "2024-09-24T14:15:22Z" status: WAITING serviceId: "YOUR_service_id" serviceId: "YOUR_service_id" updateSMSandVoiceNumber: summary: Update number with SMS and Voice configuration value: displayName: "MyPhoneNumber" smsConfiguration: servicePlanId: "string" campaignId: "YOUR_campaignId_from_TCR" voiceConfiguration: type: RTC appId: "YOUR_Voice_appId" callbackUrl: https://www.your-callback-server.com/callback updateSMSNumber: summary: Update number with SMS configuration value: displayName: "MyPhoneNumber" smsConfiguration: servicePlanId: "YOUR_servicePlanId" campaignId: "YOUR_campaignId_from_TCR" callbackUrl: https://www.your-callback-server.com/callback updateVoiceNumber: summary: Update number with Voice configuration value: displayName: "MyPhoneNumber" voiceConfiguration: type: RTC appId: "YOUR_Voice_appId" callbackUrl: https://www.your-callback-server.com/callback requestBodies: ActiveNumberRequest: description: The number body to be updated. content: application/json: schema: $ref: '#/components/schemas/ActiveNumberRequest' examples: updateSMSandVoiceNumber: $ref: "#/components/examples/updateSMSandVoiceNumber" updateSMSNumber: $ref: "#/components/examples/updateSMSNumber" updateVoiceNumber: $ref: "#/components/examples/updateVoiceNumber" RentNumberRequest: description: The request to rent a number. required: true content: application/json: schema: $ref: '#/components/schemas/RentNumberRequest' examples: activateBothSMSandVoiceNumber: $ref: "#/components/examples/activateBothSMSandVoiceNumberReq" activateSMSNumber: $ref: "#/components/examples/activateSMSNumberReq" activateVoiceNumber: $ref: "#/components/examples/activateVoiceNumberReq" activateESTNumber: $ref: "#/components/examples/activateESTNumberReq" activateFaxNumber: $ref: "#/components/examples/activateFaxNumberReq" ListAvailableNumber: description: Filter your number search. content: application/json: schema: $ref: '#/components/schemas/ListAvailableNumberRequest' responses: ActiveNumberResponse: description: A successful response, or an [Error](/docs/numbers/api-reference/error-codes/status-codes/). content: application/json: schema: $ref: '#/components/schemas/ActiveNumberResponse' examples: activateBothSMSandVoiceNumber: $ref: "#/components/examples/activateBothSMSandVoiceNumberRes" activateSMSNumber: $ref: "#/components/examples/activateSMSNumberRes" activateVoiceNumber: $ref: "#/components/examples/activateVoiceNumberRes" activateESTNumber: $ref: "#/components/examples/activateESTNumberRes" activateFaxNumber: $ref: "#/components/examples/activateFaxNumberRes" AvailableNumberResponse: description: A successful response. content: application/json: schema: $ref: '#/components/schemas/AvailableNumber' ListActiveNumbersResponse: description: A successful response. content: application/json: schema: $ref: '#/components/schemas/ListActiveNumbersResponse' ListAvailableNumbersResponse: description: A successful response. content: application/json: schema: $ref: '#/components/schemas/ListAvailableNumbersResponse' ListAvailableRegionsResponse: description: A successful response. content: application/json: schema: $ref: '#/components/schemas/ListAvailableRegionsResponse' PermissionDenied: description: 'PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.' content: application/json: schema: {} example: error: code: 403 message: "" status: "PERMISSION_DENIED" details: [] schemas: RentAnyNumberRequest: title: RentAnyNumberRequest required: - regionCode - type type: object properties: numberPattern: $ref: '#/components/schemas/NumberPattern' regionCode: type: string description: 'Region code to filter by. ISO 3166-1 alpha-2 country code of the phone number. Example: `US`, `GB` or `SE`.' type: type: string description: Number type to filter by. `MOBILE`, `LOCAL` or `TOLL_FREE`. example: MOBILE capabilities: type: array items: type: string description: Number capabilities to filter by, `SMS` and/or `VOICE`. smsConfiguration: $ref: '#/components/schemas/smsConfiguration' voiceConfiguration: $ref: '#/components/schemas/VoiceConfiguration' callbackUrl: type: string description: The callback URL to be called for a rented number's provisioning / deprovisioning operations. example: https://www.your-callback-server.com/callback description: Request message for searching and renting in one go any number that matches the search criteria. ListAvailableNumberRequest: description: Available numbers schema base. type: object properties: NumberPattern: $ref: '#/components/schemas/numberPattern.pattern' NumberPatternSearchPattern: $ref: '#/components/schemas/numberPattern.searchPattern' regionCode: $ref: '#/components/schemas/regionCode' type: $ref: '#/components/schemas/type' capabilities: $ref: '#/components/schemas/capabilities' NumberPatternSearchPattern: type: string x-enumDescriptions: START: Numbers that start with the provided sequence of digits. CONTAINS: Numbers that contain the sequence of digits entered. END: Numbers that end with the sequence of digits entered. description: The pattern to apply to searches. title: Search Pattern numberPattern.pattern: description: Sequence of digits to search for. type: string properties: NumberPattern: $ref: "#/components/schemas/NumberPattern" numberPattern.searchPattern: description: Search pattern to apply. type: string properties: NumberPatternSearchPattern: $ref: "#/components/schemas/NumberPatternSearchPattern" regionCode: description: "Region code to filter by. ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE." type: string type: description: Number type to filter by. `MOBILE`, `LOCAL` or `TOLL_FREE`. type: string x-enumDescriptions: MOBILE: Numbers that belong to a specific range. LOCAL: Numbers that are assigned to a specific geographic region. TOLL_FREE: Number that are free of charge for the calling party but billed for all arriving calls. default: MOBILE capabilities: description: Number capabilities to filter by SMS and/or VOICE. type: array properties: items: type: string x-enumDescriptions: SMS: The SMS product can use the number VOICE: The Voice product can use the number money: type: object description: An object giving details on currency code and the amount charged. properties: currencyCode: type: string example: USD description: The 3-letter currency code defined in ISO 4217. amount: type: string example: '2.00' description: |- The amount in decimal form. For example `2.00`. There are no guarantees on the precision unless documented by the message origin. The amount cannot be updated and is read-only. title: Money ActiveNumberRequest: type: object properties: displayName: type: string description: User supplied name for the phone number. smsConfiguration: $ref: '#/components/schemas/smsConfiguration' voiceConfiguration: $ref: '#/components/schemas/VoiceConfiguration' callbackUrl: type: string description: The callback URL to be called for a rented number's provisioning / deprovisioning operations. description: The phone number that has been rented by a customer and assigned to a project. title: Active Number Request ActiveNumberResponse: type: object properties: phoneNumber: type: string example: '+12025550134' description: >- The phone number in E.164 format with leading `+`. Example: `+12025550134`. projectId: type: string example: 51bc3f40-f266-4ca8-8938-a1ed0ff32b9a description: >- Project ID. Your project ID can be found on your [Sinch Customer Dashboard](https://dashboard.sinch.com/settings/project-management). displayName: type: string description: User supplied name for the phone number. regionCode: type: string example: US description: >- ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE. readOnly: true type: $ref: '#/components/schemas/NumberType' capability: description: The capability of the number. type: array example: - SMS items: $ref: '#/components/schemas/NumberCapability' money: $ref: '#/components/schemas/money' paymentIntervalMonths: type: integer format: int32 description: How often the recurring price is charged in months. readOnly: true nextChargeDate: type: string format: date-time description: The date of the next charge. readOnly: true expireAt: type: string format: date-time description: The timestamp when the subscription will expire if an expiration date has been set. readOnly: true smsConfiguration: type: object required: - servicePlanId properties: servicePlanId: type: string description: The `servicePlanId` can be found in the [Sinch Customer Dashboard](https://dashboard.sinch.com/sms/api/rest). The service plan ID is what ties this to the configured SMS service. scheduledProvisioning: $ref: '#/components/schemas/scheduledProvisioning' campaignId: type: string description: |- Only for US phone numbers. This `campaignId` is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The `campaignId` is found on your TCR platform. description: |- The current SMS configuration for this number. Once the `servicePlanId` is sent, it enters scheduled provisioning. The status of scheduled provisioning will show under a `scheduledProvisioning` object if it's still running. Once processed successfully, the `servicePlanId` sent will appear directly under the `smsConfiguration` object. title: SMS Configuration voiceConfiguration: $ref: "#/components/schemas/VoiceConfiguration" callbackUrl: type: string description: The callback URL to be called for a rented number's provisioning / deprovisioning operations. example: https://www.your-callback-server.com/callback description: The phone number that has been bought by a customer and assigned to a project. title: Active Number Response AvailableNumber: type: object properties: phoneNumber: type: string example: '+12025550134' description: The phone number in E.164 format with leading `+`. Example `+12025550134`. readOnly: true regionCode: type: string example: US description: "ISO 3166-1 alpha-2 country code of the phone number. Example: US, UK or SE." readOnly: true type: $ref: '#/components/schemas/NumberType' capability: type: array description: The capability of the number. example: - SMS - VOICE items: $ref: '#/components/schemas/NumberCapability' setupPrice: $ref: '#/components/schemas/money' monthlyPrice: $ref: '#/components/schemas/money' paymentIntervalMonths: type: integer format: int32 description: How often the recurring price is charged in months. readOnly: true supportingDocumentationRequired: type: boolean description: Whether or not supplementary documentation will be required to complete the number rental. readOnly: true description: >- The phone numbers that are available to be rented in [dashboard.sinch.com](https://dashboard.sinch.com/numbers/buy-numbers) or via the public numbers API. title: Available Number AvailableRegion: type: object properties: regionCode: type: string example: US description: 'ISO 3166-1 alpha-2 region code. Examples: US, UK or SE.' readOnly: true regionName: type: string example: United States description: >- Display name of the region. Examples: United States, United Kingdom or Sweden. readOnly: true types: type: array example: - MOBILE items: $ref: '#/components/schemas/NumberType' description: >- A list of the different number types available. Examples: `MOBILE` or `LOCAL`. readOnly: true description: A region for which numbers are provided. title: Available Region ListActiveNumbersResponse: type: object properties: activeNumbers: type: array items: $ref: '#/components/schemas/ActiveNumberResponse' description: >- List of numbers associated to the client project specified in `ListActiveNumbers`. nextPageToken: type: string title: The token to be used for listing the next page. totalSize: type: integer format: int32 title: The maximum number of results returned. description: Response message to list your active phone numbers. title: Active Numbers Response ListAvailableNumbersResponse: type: object properties: availableNumbers: type: array items: $ref: '#/components/schemas/AvailableNumber' description: List of available phone numbers. description: Response message to list available phone numbers. title: Available Numbers Response ListAvailableRegionsResponse: type: object properties: availableRegions: type: array items: $ref: '#/components/schemas/AvailableRegion' title: List of regions for which numbers are provided. description: Response message to list regions for which numbers are provided. title: List Available Regions Response NumberCapability: type: string x-enumDescriptions: SMS: The SMS product can use the number. VOICE: The Voice product can use the number. default: SMS description: "The capabilities the phone number supports: SMS, Voice, or both" title: Capability NumberPattern: type: object properties: pattern: type: string description: Sequence of digits to search for. searchPattern: $ref: '#/components/schemas/NumberPatternSearchPattern' title: Search Pattern NumberType: type: string x-enumDescriptions: MOBILE: Numbers that belong to a specific range. LOCAL: Numbers that are assigned to a specific geographic region. TOLL_FREE: Numbers that are free of charge for the calling party but billed for all arriving calls. default: MOBILE description: The number type. title: Type ProvisioningStatus: default: WAITING description: The provisioning status. It will be either `WAITING`, `IN_PROGRESS` or `FAILED`. If the provisioning fails, a reason for the failure will be provided. See a full list of provisioning error descriptions and troubleshooting recommendations. x-enumDescriptions: - WAITING - IN_PROGRESS - FAILED title: Provisioning Status RentNumberRequest: type: object properties: smsConfiguration: $ref: '#/components/schemas/smsConfiguration' voiceConfiguration: $ref: '#/components/schemas/VoiceConfiguration' callbackUrl: type: string description: The callback URL to be called for a rented number's provisioning / deprovisioning operations. description: Request message for renting a phone number. title: Rent Number Request RentNumberResponse: type: object properties: smsConfiguration: type: object required: - servicePlanID properties: servicePlanId: type: string description: The servicePlanId for this number (tied to the configured SMS service). During scheduled provisioning, this value may be empty in a response if it is still processing or if it has failed. The status of scheduled provisioning will show under a `scheduledProvisioning` object if it's still running. Once processed successfully, the `servicePlanId` sent will appear directly under the `smsConfiguration` object. scheduledProvisioning: $ref: '#/components/schemas/scheduledProvisioning' campaignId: type: string description: |- Only for US phone numbers. This `campaignId` is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The `campaignId` is found on your TCR platform. description: The current SMS configuration for this number. title: SMS Configuration voiceConfiguration: $ref: '#/components/schemas/VoiceConfiguration' callbackUrl: type: string description: The callback URL to be called for a rented number's provisioning / deprovisioning operations. description: Request message for renting a phone number. title: Rent Number Request scheduledProvisioning: type: object description: This object is temporary and will appear while the scheduled provisioning for SMS is processing. Once it has successfully processed, only the ID of the SMS configuration will display. properties: servicePlanId: type: string example: 8200000f74924bd6800000b212f00000 description: Service plan of the scheduled provisioning task. readOnly: true status: $ref: '#/components/schemas/ProvisioningStatus' lastUpdatedTime: type: string format: date-time description: Timestamp when the status was last updated. readOnly: true campaignId: type: string description: Campaign ID of the scheduled provisioning task. Note that the campaign ID is only for US numbers as it relates to 10DLC. readOnly: true errorCodes: type: array items: $ref: '#/components/schemas/SmsErrorCode' description: >- The provisioning status codes are found here. title: Scheduled SMS Provisioning smsConfiguration: type: object required: - servicePlanId properties: servicePlanId: type: string description: The `servicePlanId` can be found in the [Sinch Customer Dashboard](https://dashboard.sinch.com/sms/api/rest). The service plan ID is what ties this number to the configured SMS service. campaignId: type: string description: |- Only for US phone numbers. This `campaignId` is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The `campaignId` is found on your TCR platform. description: |- The current SMS configuration for this number. Once the `servicePlanId` is sent, it enters scheduled provisioning. The status of scheduled provisioning will show under a `scheduledProvisioning` object if it's still running. Once processed successfully, the `servicePlanId` sent will appear directly under the `smsConfiguration` object. title: SMS Configuration SmsErrorCode: type: string default: PARTNER_SERVICE_UNAVAILABLE description: The SMS error codes are found here. title: Type VoiceApplicationType: type: string description: The voice application type. Examples are RTC, EST, FAX x-enumDescriptions: RTC: Voice [see documentation](https://developers.sinch.com/docs/voice) EST: Elastic SIP Trunking [see documentation](https://developers.sinch.com/docs/est) FAX: FAX application [see documentation](https://developers.sinch.com/docs/fax/overview) enum: - RTC - EST - FAX VoiceConfigurationCommon: title: Common VoiceConfiguration fields type: object required: - type properties: type: $ref: '#/components/schemas/VoiceApplicationType' lastUpdatedTime: type: string description: Timestamp when the status was last updated. format: date-time readOnly: true scheduledVoiceProvisioning: $ref: '#/components/schemas/ScheduledVoiceProvisioning' VoiceTrunkId: type: object properties: trunkId: type: string description: The trunk ID if the type is EST. The `trunkId` can be found in your [Sinch Customer Dashboard](https://dashboard.sinch.com/trunks/your-trunks). VoiceServiceId: type: object properties: serviceId: type: string description: The service ID if the type is FAX. The `serviceId` can be found in your [Sinch Customer Dashboard](https://dashboard.sinch.com/fax/services). VoiceAppId: type: object properties: appId: type: string description: Your app ID for the Voice API. The `appId` can be found in your [Sinch Customer Dashboard](https://dashboard.sinch.com/voice/apps). VoiceConfigurationRTC: title: RTC VoiceConfiguration type: object allOf: - $ref: '#/components/schemas/VoiceConfigurationCommon' - $ref: '#/components/schemas/VoiceAppId' VoiceConfigurationEST: title: EST VoiceConfiguration type: object allOf: - $ref: '#/components/schemas/VoiceConfigurationCommon' - $ref: '#/components/schemas/VoiceTrunkId' VoiceConfigurationFAX: title: FAX VoiceConfiguration type: object allOf: - $ref: '#/components/schemas/VoiceConfigurationCommon' - $ref: '#/components/schemas/VoiceServiceId' VoiceConfiguration: title: VoiceConfiguration type: object oneOf: - $ref: "#/components/schemas/VoiceConfigurationRTC" - $ref: "#/components/schemas/VoiceConfigurationEST" - $ref: "#/components/schemas/VoiceConfigurationFAX" discriminator: propertyName: type mapping: RTC: "#/components/schemas/VoiceConfigurationRTC" EST: "#/components/schemas/VoiceConfigurationEST" FAX: "#/components/schemas/VoiceConfigurationFAX" description: The current voice configuration for this number. During scheduled provisioning, the app ID, service ID, or trunk ID value may be empty in a response if it is still processing or if it has failed. The status of scheduled provisioning will show under a `scheduledVoiceProvisioning` object if it's still running. Once processed successfully, the `appId`/`serviceId`/`trunkId` sent will appear directly under the `voiceConfiguration` object. ScheduledVoiceProvisioningCommon: type: object allOf: - type: object properties: type: $ref: '#/components/schemas/VoiceApplicationType' lastUpdatedTime: type: string description: Timestamp when the status was last updated. format: date-time readOnly: true status: $ref: '#/components/schemas/ProvisioningStatus' ScheduledVoiceProvisioningEST: type: object allOf: - $ref: '#/components/schemas/ScheduledVoiceProvisioningCommon' - $ref: '#/components/schemas/VoiceTrunkId' ScheduledVoiceProvisioningFAX: type: object allOf: - $ref: '#/components/schemas/ScheduledVoiceProvisioningCommon' - $ref: '#/components/schemas/VoiceServiceId' ScheduledVoiceProvisioningRTC: type: object allOf: - $ref: '#/components/schemas/ScheduledVoiceProvisioningCommon' - $ref: '#/components/schemas/VoiceAppId' ScheduledVoiceProvisioning: type: object readOnly: true description: Represents the ongoing or failed scheduled voice provisioning job. This field will be empty if the number was successfully provisioned provisioned for voice. required: - type oneOf: - $ref: "#/components/schemas/ScheduledVoiceProvisioningEST" - $ref: "#/components/schemas/ScheduledVoiceProvisioningFAX" - $ref: "#/components/schemas/ScheduledVoiceProvisioningRTC" discriminator: propertyName: type mapping: EST: "#/components/schemas/ScheduledVoiceProvisioningEST" FAX: "#/components/schemas/ScheduledVoiceProvisioningFAX" RTC: "#/components/schemas/ScheduledVoiceProvisioningRTC" title: Scheduled Voice Provisioning CallbackConfiguration: description: Response message containing the callbacks configuration for a specific project. type: object properties: projectId: type: string description: ID of the project the configuration belongs to. example: "a99aa9aa-b888-777c-dd6d-ee55e5555555" hmacSecret: type: string description: The HMAC secret used for hashing the callback body using the HMAC-SHA1 algorithm - and for creating the `X-Sinch-Signature` header. example: "YOUR_hmac_secret" CallbackConfigurationUpdate: title: CallbackConfigurationUpdate type: object properties: hmacSecret: type: string description: The HMAC secret to be updated for the specified project description: The request to update the callbacks configuration for the current project. CallbackPayload: type: object properties: eventId: type: string description: The ID of the event. example: "abcd1234efghijklmnop567890" timestamp: type: string description: The date and time when the callback was created and added to the callbacks queue. example: "2023-06-06T07:45:27.785357" projectId: type: string description: The ID of the project to which the event belongs. example: "abcd12ef-ab12-ab12-bc34-abcdef123456" resourceId: type: string description: The unique identifier of the resource, depending on the resource type. For example, a phone number, a hosting order ID, or a brand ID. example: "+12345612345" resourceType: type: string description: The type of the resource. x-enumDescriptions: ACTIVE_NUMBER: Numbers which are already active and updated with new campaign IDs or service plan IDs. example: "ACTIVE_NUMBER" eventType: type: string description: The type of the event. x-enumDescriptions: PROVISIONING_TO_SMS_PLATFORM: An event that occurs when a number is linked to a Service Plan ID. DEPROVISIONING_FROM_SMS_PLATFORM: An event that occurs when a number is unlinked from a Service Plan ID. PROVISIONING_TO_CAMPAIGN: An event that occurs when a number is linked to a Campaign. DEPROVISIONING_FROM_CAMPAIGN: An event that occurs when a number is unlinked from a Campaign. PROVISIONING_TO_VOICE_PLATFORM: An event that occurs when a number is enabled for Voice operations. DEPROVISIONING_TO_VOICE_PLATFORM: An event that occurs when a number is disabled for Voice operations. example: "PROVISIONING_TO_CAMPAIGN" status: type: string description: The status of the event. For example, `SUCCEEDED` or `FAILED`. example: "FAILED" failureCode: type: string description: If the status is FAILED, a failure code will be provided. For numbers provisioning to SMS platform, there won't be any extra `failureCode`, as the result is binary. For campaign provisioning-related failures, refer to the list for the possible values. example: CAMPAIGN_NOT_AVAILABLE enum: - CAMPAIGN_NOT_AVAILABLE - EXCEEDED_10DLC_LIMIT - NUMBER_PROVISIONING_FAILED - PARTNER_SERVICE_UNAVAILABLE - CAMPAIGN_PENDING_ACCEPTANCE - MNO_SHARING_ERROR - CAMPAIGN_PROVISIONING_FAILED - CAMPAIGN_EXPIRED - CAMPAIGN_MNO_REJECTED - CAMPAIGN_MNO_SUSPENDED - CAMPAIGN_MNO_REVIEW - INSUFFICIENT_BALANCE - MOCK_CAMPAIGN_NOT_ALLOWED - TFN_NOT_ALLOWED - INVALID_NNID InvalidArgument: type: object properties: error: type: object properties: code: type: integer enum: - 400 message: type: string status: type: string enum: - INVALID_ARGUMENT details: type: array items: $ref: '#/components/schemas/BadRequest' BadRequest: type: object properties: type: type: string enum: - BadRequest fieldViolations: type: array items: $ref: '#/components/schemas/FieldViolation' FieldViolation: type: object properties: field: type: string description: type: string NotFound: type: object properties: error: type: object properties: code: type: integer enum: - 404 message: type: string status: type: string enum: - NOT_FOUND details: type: array items: type: object InternalError: type: object properties: error: type: object properties: code: type: integer enum: - 500 message: type: string status: type: string enum: - INTERNAL - UNKNOWN details: type: array items: type: object securitySchemes: Basic: type: http scheme: basic description: Your key ID and Key secret serve as the username and password, respectively. Both can be found in the Sinch Customer Dashboard.For more information about basic authentication in the Numbers API, click [here](/docs/numbers/api-reference/authentication/basic). OAuth2.0: type: oauth2 description: The username and password are your Key ID and Key Secret from the Access keys section in the Sinch Customer Dashboard. Exchange these for a bearer token (access token). Learn how [here](/docs/numbers/api-reference/authentication/oauth). flows: clientCredentials: tokenUrl: https://auth.sinch.com/oauth2/token scopes: {}