# Numbers | Sinch

# Overview

The Numbers API enables you to search for, view, and activate 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 activated 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.

## 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
License: MIT

## Servers

Global API
```
https://numbers.api.sinch.com
```

## Security

### Basic

Your key ID and Key secret serve as the username and password, respectively. Both can be found in the [Sinch Customer Dashboard](https://dashboard.sinch.com/settings/access-keys). For more information about basic authentication in the Numbers API, click [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/basic).

Type: http
Scheme: basic

### OAuth2.0

The username and password are your Key ID and Key Secret from the [Access keys section](https://dashboard.sinch.com/settings/access-keys) in the Sinch Customer Dashboard. Exchange these for a bearer token (access token). Learn how [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth).

Type: oauth2

## Download OpenAPI description

[Numbers | Sinch](https://developers.sinch.com/_bundle/docs/numbers/api-reference/numbers.yaml)

## Available Numbers

You can use the Available Number API to search for available numbers or activate an available number.

### Activate a new phone number

 - [POST /v1/projects/{projectId}/availableNumbers/{phoneNumber}:rent](https://developers.sinch.com/docs/numbers/api-reference/numbers/available-number/numberservice_rentnumber.md): 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.

### Rent any number that matches the criteria

 - [POST /v1/projects/{projectId}/availableNumbers:rentAny](https://developers.sinch.com/docs/numbers/api-reference/numbers/available-number/numberservice_rentanynumber.md): Activates a phone number that matches the search criteria provided in the request. Currently the rentAny operation works only for US LOCAL numbers

### Search for available phone numbers

 - [GET /v1/projects/{projectId}/availableNumbers](https://developers.sinch.com/docs/numbers/api-reference/numbers/available-number/numberservice_listavailablenumbers.md): 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.

### Search for a specific phone number

 - [GET /v1/projects/{projectId}/availableNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/numbers/available-number/numberservice_getavailablenumber.md): 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.

## Number Order

You can use the Number Order API to search for available numbers or activate an available number after providing KYC info.

Steps for buying a 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.
2. "Search for available phone numbers" endpoint: search numbers you may want to buy.
3. "Create a number order" endpoint: create the Number Order for a specific phone number or for a set of criteria (max 1 number per order supported now), which reserved the number for 48h, 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

You can follow a detailed tutorial outlining the entire ordering process [here](https://developers.sinch.com/docs/numbers/kyc-numbers-order).

### Lookup number requirements

 - [POST /v1/projects/{projectId}/numberOrders:lookupNumberRequirements](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order/lookupnumberrequirements.md): Returns required KYC fields info based on number type & country legislation.

You can follow a detailed tutorial outlining the entire ordering process here.

### Create a number order

 - [POST /v1/projects/{projectId}/numberOrders:createNumberOrder](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order/createnumberorder.md): Create a number order for a specific number or a set of criteria (quantity, pattern etc.) - reserves the provider numbers for 48h and creates entities for collecting KYC info.

You can follow a detailed tutorial outlining the entire ordering process here.

### Get a number order

 - [GET /v1/projects/{projectId}/numberOrders/{numberOrderId}](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order/getnumberorder.md): Returns the number order alongside all reserved numbers.

You can follow a detailed tutorial outlining the entire ordering process here.

### Update number order registration

 - [PUT /v1/projects/{projectId}/numberOrders/{numberOrderId}/registration](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order/updatenumberorderregistration.md): Updates the registration (vehicle for KYC info) for a specific number order. Validated against the country requirements revealed by the "Lookup number requirements" endpoints.

You can follow a detailed tutorial outlining the entire ordering process here.

### Get number order registration

 - [GET /v1/projects/{projectId}/numberOrders/{numberOrderId}/registration](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order/getnumberorderregistration.md): Retrieves the Registration submitted for a number order via the "Update number order registration" endpoint.

You can follow a detailed tutorial outlining the entire ordering process here.

### Upload an attachment for a number order

 - [POST /v1/projects/{projectId}/numberOrders/{numberOrderId}/attachments/{attachmentId}](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order/uploadnumberorderattachment.md): Upload file attachments to a number order registration. Mandatory only if revealed in the requirements returned by the "Lookup number requirements" endpoint. 

The "attachmentId" URL parameter is the one returned by the "Lookup number requirements" endpoint.

You can follow a detailed tutorial outlining the entire ordering process here.

### Submit number order

 - [POST /v1/projects/{projectId}/numberOrders/{numberOrderId}/submit](https://developers.sinch.com/docs/numbers/api-reference/numbers/number-order/submitnumberorder.md): Submits the order for review, assuming the KYC info and attachments were submitted using their dedicated endpoints.

You can follow a detailed tutorial outlining the entire ordering process here.

## Active Numbers

You can use the Active Number API to manage numbers you own. Release numbers from projects or list all numbers assigned to a project.

### Lists active numbers for a project

 - [GET /v1/projects/{projectId}/activeNumbers](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_listactivenumbers.md): Lists all active numbers for a project.

### Update an active phone number

 - [PATCH /v1/projects/{projectId}/activeNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_updateactivenumber.md): 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.

### Retrieve an active phone number

 - [GET /v1/projects/{projectId}/activeNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_getactivenumber.md): Retrieve a specific active phone number.

### Release an active number from the project

 - [POST /v1/projects/{projectId}/activeNumbers/{phoneNumber}:release](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_releasenumber.md): With this endpoint, you can cancel your subscription for a specific phone number.

### Get the emergency address for a number

 - [GET /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_getemergencyaddress.md): With this endpoint, you can retrieve the emergency address associated with this number.

### Add a emergency address for a number

 - [POST /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:provision](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_provisionemergencyaddress.md): With this endpoint, you can provision an emergency address associated with this number.

### Remove the emergency address for a number.

 - [POST /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:deprovision](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_deprovisionemergencyaddress.md): With this endpoint, you can deprovision the emergency address associated with this number.

### Validate the emergency address for a number.

 - [POST /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:validate](https://developers.sinch.com/docs/numbers/api-reference/numbers/active-number/numberservice_validateemergencyaddress.md): With this endpoint, you can validate the emergency address associated with this number.

## Available Regions

You can use the Available Regions API to list all of the regions that have numbers assigned to a project.

### List available regions

 - [GET /v1/projects/{projectId}/availableRegions](https://developers.sinch.com/docs/numbers/api-reference/numbers/available-regions/numberservice_listavailableregions.md): Lists all regions for numbers provided for the project ID.

## Numbers Callbacks

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](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.

### Get callbacks configuration

 - [GET /v1/projects/{projectId}/callbackConfiguration](https://developers.sinch.com/docs/numbers/api-reference/numbers/numbers-callbacks/getcallbackconfiguration.md): Returns the callbacks configuration for the specified project

### Update callback configuration

 - [PATCH /v1/projects/{projectId}/callbackConfiguration](https://developers.sinch.com/docs/numbers/api-reference/numbers/numbers-callbacks/updatecallbackconfiguration.md): Updates the callbacks configuration for the specified project

### Event notification

 - [POST EventsCallback](https://developers.sinch.com/docs/numbers/api-reference/numbers/numbers-callbacks/importednumberservice_eventscallback.md): A notification of an event sent to your configured callback URL.