openapi: '3.1.0' info: title: Numbers | Sinch description: >- An API service for getting, listing and managing Sinch virtual 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: [] 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. Assign numbers to projects, 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. x-explorer-enabled: false x-samples-languages: - curl - java - csharp - node - php paths: '/v1/projects/{projectId}/availableNumbers/{phoneNumber}:rent': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/phoneNumber' post: summary: Activate a new virtual number description: |- Activate a virtual 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/) tags: - Available Number '/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 virtual numbers for a project description: Lists all virtual 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/) tags: - Active Number '/v1/projects/{projectId}/activeNumbers/{phoneNumber}': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/phoneNumber' patch: summary: Update a virtual phone number description: >- Update a virtual phone number. For example: you can move a number between different SMS services and give it a new, friendly name. To update the name that displays for a customer, modify the `displayName` parameter. You'll use `smsConfiguration` to update your SMS number and `voiceConfiguration` to update Voice. To update for both, add both objects. Within these objects, you can update the service plan ID, campaign ID, and scheduled provisioning status. You can also update the type of number, currency type and amount. Note: You cannot add both objects if you only need to update one object. For example, if you only need to reconfigure `smsConfiguration` for SMS messaging, do not add the `voiceConfiguration` object or it will result in an error. 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/) tags: - Active Number get: summary: Get a virtual 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/) tags: - Active Number '/v1/projects/{projectId}/activeNumbers/{phoneNumber}:release': parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/phoneNumber' post: summary: Release a virtual number from the project description: With this endpoint, you can cancel your subscription for a specific virtual 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/) 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: description: Search with filters $ref: '#/components/schemas/ListAvailableNumberRequest' get: summary: Search for virtual numbers description: |- Search for virtual 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/) 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/) tags: - Available Regions 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`, `CONTAIN`, and `END`. in: query required: false schema: type: string enum: - START - CONTAIN - 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`. CONTAIN: 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 default: 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. default: 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: activateSMSNumber: summary: Activate number with SMS configuration value: smsConfiguration: servicePlanId: "YOUR_SMS_servicePlanId" campaignId: "YOUR_campaignId_from_TCR" activateBothSMSandVoiceNumber: summary: Activate number with SMS and Voice configuration value: smsConfiguration: servicePlanId: "YOUR_SMS_servicePlanId" voiceConfiguration: appId: "YOUR_Voice_appId" activateVoiceNumber: summary: Activate number with Voice configuration value: voiceConfiguration: appId: "YOUR_appId" updateSMSandVoiceNumber: summary: Update number with SMS and Voice configuration value: displayName: "MyPhoneNumber" smsConfiguration: servicePlanId: "string" campaignId: "YOUR_campaignId_from_TCR" voiceConfiguration: appId: "YOUR_Voice_appId" updateSMSNumber: summary: Update number with SMS configuration value: displayName: "MyPhoneNumber" smsConfiguration: servicePlanId: "YOUR_servicePlanId" campaignId: "YOUR_campaignId_from_TCR" updateVoiceNumber: summary: Update number with Voice configuration value: displayName: "MyPhoneNumber" voiceConfiguration: appId: "YOUR_Voice_appId" 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/activateBothSMSandVoiceNumber" activateSMSNumber: $ref: "#/components/examples/activateSMSNumber" activateVoiceNumber: $ref: "#/components/examples/activateVoiceNumber" 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' 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: 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' 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 virtual numbers. This campaign ID relates to 10DLC numbers. So, it is the current campaign ID for this number. The `campaign_id` 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: 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) under Voice, then apps. scheduledVoiceProvisioning: $ref: '#/components/schemas/scheduledVoiceProvisioning' lastUpdatedTime: type: string format: date-time description: Timestamp when the status was last updated. readOnly: true description: |- The current voice configuration for this number. During scheduled provisioning, the app 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 `scheduledProvisioning` object if it's still running. Once processed successfully, the `appId` sent will appear directly under the `voiceConfiguration` object. title: Voice Configuration 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' 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 virtual numbers. This campaign ID relates to 10DLC numbers. So, it is the current campaign ID for this number. The `campaign_id` is found on your TCR platform. description: The current SMS configuration for this number. title: SMS Configuration voiceConfiguration: $ref: '#/components/schemas/VoiceConfiguration' 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 scheduledVoiceProvisioning: type: object description: This object is temporary and will appear while the scheduled voice provisioning is processing. Once it has successfully processed, only the ID of the Voice configuration will display. properties: appId: type: string description: RTC application ID 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 title: Scheduled Voice 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 virtual numbers. This campaign ID relates to 10DLC numbers. 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 VoiceConfiguration: 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) under Voice, then apps. lastUpdatedTime: type: string format: date-time description: Timestamp when the status was last updated. readOnly: true description: The current voice configuration for this number. During scheduled provisioning, the app 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` sent will appear directly under the `voiceConfiguration` object. title: Voice Configuration securitySchemes: Basic: type: http scheme: basic description: For more information about basic authentication, see [Authentication](/docs/numbers/api-reference/index.md#authentication). oAuth2: type: oauth2 description: The username and password are your KEY ID and SECRET from the [Access keys sections](https://dashboard.sinch.com/settings/access-keys) in the Sinch Customer Dashboard. flows: clientCredentials: tokenUrl: https://auth.sinch.com/oauth2/token scopes: {}