Sinch Numbers API

openapi: 3.2.0
info:
  title: Numbers | Sinch
  description: '# Overview


    The Numbers API enables you to search for, buy, view, and manage numbers. It''s considered a precursor to other APIs in the Sinch product family. The numbers API can be used in tandem with any of our APIs that perform messaging or calling. Once you have bought your numbers, you can then use the various other APIs, such as [SMS](https://developers.sinch.com/docs/sms/) or [Voice](https://developers.sinch.com/docs/voice/), to assign and use those numbers.


    ## Choosing how to buy a number


    Use the [Number Order](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order) API to buy numbers. It supports numbers from all regions and of all number types, and it collects any registration (KYC) information and supporting documents a region requires:


    1. Check what the region and number type require ("Lookup number requirements").

    2. Find a number to buy ("Search for available phone numbers" in the [Available Numbers](https://developers.sinch.com/docs/numbers/api-reference/numbers/available-number) API), or skip this step and order by criteria instead.

    3. Create the order, provide any required registration information and documents, and submit it.


    For a step-by-step walkthrough, see [Ordering numbers that meet specific requirements](https://developers.sinch.com/docs/numbers/kyc-numbers-order).


    **Deprecated:** The Available Numbers activation endpoints, "Activate a new phone number" (`availableNumbers/{phoneNumber}:rent`) and "Rent any number that matches the criteria" (`availableNumbers:rentAny`), are deprecated and only support US `LOCAL` numbers. They remain available for existing integrations, but new integrations should use the Number Order API. The Available Numbers search endpoints aren''t deprecated and work for all regions and number types.


    ## Numbers REST formats and conventions


    Let''s take a brief look at some of the formats used in the REST API.


    ### JSON


    JSON (`application/json`) is the content type of both requests and responses if not otherwise specified.


    Requests with invalid JSON will be rejected.


    ### Null values


    Null values can be omitted in requests and will be omitted in responses. In some cases, explicitly setting `null` will overwrite a previously set value with `null`.


    ### Phone numbers


    Only phone numbers in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) standard format are accepted by the API.


    #### Examples:


    - **US phone number:** `+13059394139`

    - **UK phone number:** `+447478727259`

    - **SE phone number:** `+46113232516`


    ## Status codes


    A summary of status codes can be found on the [HTTP status codes page](https://developers.sinch.com/docs/numbers/api-reference/error-codes/status-codes).


    ## IP addresses for callbacks


    To successfully use callbacks with Numbers, add the following IP addresses to your allowlist:


    - 54.76.19.159

    - 54.78.194.39

    - 54.155.83.128


    ## New features


    New features might result in additional request and response parameters. New request parameters will either have a default value or be considered optional to retain backwards compatibility. It''s highly recommended to ignore any unexpected parameters when reading JSON in API responses and in callback handlers.

    '
  version: 1.0.3
  contact:
    name: Support
    url: https://www.sinch.com
    email: Support@sinch.com
  license:
    name: MIT
    url: https://www.sinch.com/legal
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 numbers that are available to buy, in any region and of any number type, and to check a specific number''s availability, price, and capabilities.


    To buy a number you found, use the [Number Order](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order) API.


    **Deprecated:** The activation endpoints in this API, "Activate a new phone number" and "Rent any number that matches the criteria", are deprecated and only support US `LOCAL` numbers. They remain available for existing integrations, but new integrations should use the [Number Order](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order) API, which supports numbers from all regions and of all number types.'
  x-displayName: Available Numbers
- name: Number Order
  description: 'You can use the Number Order API to buy numbers. This is the recommended way to buy numbers: it supports numbers from all regions and of all number types, including numbers that require registration (KYC) information and supporting documents.


    You can create an order in one of two ways, and they behave differently:

    - **Order specific phone numbers** (`numberOrderOption`): order a phone number you found with "Search for available phone numbers". Only one phone number per order is currently supported. The order reserves the number, lets you provide the information the region requires, and must then be submitted with the "Submit number order" endpoint. The number isn''t activated immediately: track the order''s `state` with the "Get a number order" endpoint or the `NUMBER_ORDER_PROCESSING` callbacks.

    - **Order by quantity** (`quantityOrderOption`): order between 1 and 100 numbers that match your criteria (pattern, capabilities), without choosing the specific numbers. The numbers are purchased as soon as the order is created. No registration (KYC) information, attachments or "Submit number order" call is needed, so you can skip the lookup and the steps below. Track the order''s `state` with the "Get a number order" endpoint or the `NUMBER_ORDER_PROCESSING` callbacks.


    Steps for buying a specific number via an order and providing the required KYC information:

    1. "Lookup number requirements" endpoint: look up country KYC requirements to establish which fields / information needs to be provided as part of buying the phone number. Also reveals if any attachment files need to be provided. A `404 NOT_FOUND` response ("Number requirements not found") means the region and number type have no requirements: skip steps 4 and 5 and submit the order right after creating it.

    2. "Search for available phone numbers" endpoint (in the Available Numbers API): search the numbers you may want to buy.

    3. "Create a number order" endpoint: create the Number Order for a specific phone number (`numberOrderOption`), which reserves the number for a period between 30 minutes and 48 hours (check the expireTime field), giving plenty of time to call the other endpoint to submit the fields required as revealed by the API at 1. and also to hit the final Submit endpoint.

    4. "Update number order registration" endpoint: update the order Registration (container for the actual KYC required fields / information revealed at step #1). This is validated on the spot for required / optional fields, fields lengths etc. (also revealed at step #1).

    5. "Upload an attachment for a number order" endpoint: upload file attachments - only if mandatory as per requirements revealed by step #1. AttachmentId necessary for the URL will be returned at step #1.

    6. "Submit number order" endpoint: submit the order - final step after creating the order and providing registration info and (if required) attachments. If the lookup at step 1 found no requirements, nothing else is needed before submitting.


    You can follow a detailed tutorial outlining the entire ordering process [here](https://developers.sinch.com/docs/numbers/kyc-numbers-order).'
  x-displayName: Number Order
- 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.
  x-displayName: Active Numbers
- 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.


    Callbacks for all eventTypes - except NUMBER_ORDER_PROCESSING - will use 2 values for the status field: SUCCEEDED or FAILED. For NUMBER_ORDER_PROCESSING eventsTypes, the status field will reflect the Number Order state transition that happened, ex: IN_REVIEW, BLOCKED, COMPLETED, REJECTED, EXPIRED.


    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](https://developers.sinch.com/docs/numbers/api-reference/numbers/numbers-callbacks/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](https://developers.sinch.com/docs/numbers/api-reference/numbers/numbers-callbacks/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


# --- truncated at 32 KB (168 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-numbers-api-openapi.yml