Skip to content
Numbers/
/
/
Get callbacks configurati...

Numbers | Sinch (1.0.3)

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 or 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 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.

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.

Download OpenAPI description
numbers.json
numbers.yaml
Overview
URL

https://www.sinch.com

Support

Support@sinch.com

License

MIT

Languages
Servers
Global API

https://numbers.api.sinch.com/

Available Number

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

Operations

Active Number

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

Operations

Available Regions

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

Operations

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
OperationsWebhooks

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. 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) 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

Request

Returns the callbacks configuration for the specified project

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
curl -i -X GET \
  -u <username>:<password> \
  https://numbers.api.sinch.com/v1/projects/YOUR_projectId/callbackConfiguration

Responses

Callbacks configuration

Bodyapplication/json
projectIdstring

ID of the project the configuration belongs to.

Example: "a99aa9aa-b888-777c-dd6d-ee55e5555555"
hmacSecretstring

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"
Response
application/json
{
  "projectId": "a99aa9aa-b888-777c-dd6d-ee55e5555555",
  "hmacSecret": "YOUR_hmac_secret"
}

Update callback configuration

Request

Updates the callbacks configuration for the specified project

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: YOUR_projectId
Bodyapplication/json

The callback configuration details to be updated.

hmacSecretstring

The HMAC secret to be updated for the specified project

curl -i -X PATCH \
  -u <username>:<password> \
  https://numbers.api.sinch.com/v1/projects/YOUR_projectId/callbackConfiguration \
  -H 'Content-Type: application/json' \
  -d '{
    "hmacSecret": "string"
  }'

Responses

Callback configuration

Bodyapplication/json
projectIdstring

ID of the project the configuration belongs to.

Example: "a99aa9aa-b888-777c-dd6d-ee55e5555555"
hmacSecretstring

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"
Response
application/json
{
  "projectId": "a99aa9aa-b888-777c-dd6d-ee55e5555555",
  "hmacSecret": "YOUR_hmac_secret"
}

Event notificationWebhook

Request

A notification of an event sent to your configured callback URL.

Security
Basic or OAuth2.0
Bodyapplication/json
eventIdstring

The ID of the event.

Example: "abcd1234efghijklmnop567890"
timestampstring

The date and time when the callback was created and added to the callbacks queue.

Example: "2023-06-06T07:45:27.785357"
projectIdstring

The ID of the project to which the event belongs.

Example: "abcd12ef-ab12-ab12-bc34-abcdef123456"
resourceIdstring

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"
resourceTypestring(ResourceType)

The type of the resource.

ValueDescription
ACTIVE_NUMBER

Numbers which are already active and updated with new campaign IDs or service plan IDs.

Example: "ACTIVE_NUMBER"
eventTypestring

The type of the event.

Enum ValueDescription
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"
statusstring

The status of the event. For example, SUCCEEDED or FAILED.

Enum ValueDescription
SUCCEEDED

The event has succeeded.

FAILED

The event has failed.

Example: "FAILED"
failureCodestring

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.

Enum ValueDescription
CAMPAIGN_NOT_AVAILABLE

The specified campaign is not available.

EXCEEDED_10DLC_LIMIT

Exceeded the limit for 10DLC.

NUMBER_PROVISIONING_FAILED

Provisioning the number failed.

PARTNER_SERVICE_UNAVAILABLE

The third party service is unavailable.

CAMPAIGN_PENDING_ACCEPTANCE

The campaign is not yet accepted.

MNO_SHARING_ERROR

Error with MNO.

CAMPAIGN_PROVISIONING_FAILED

The campaign failed to provision.

CAMPAIGN_EXPIRED

The campaign expired.

CAMPAIGN_MNO_REJECTED

The campaign MNO was rejected.

CAMPAIGN_MNO_SUSPENDED

The campaign MNO was suspended.

Example: "CAMPAIGN_NOT_AVAILABLE"
application/json
{
  "eventId": "abcd1234efghijklmnop567890",
  "timestamp": "2023-06-06T07:45:27.785357",
  "projectId": "abcd12ef-ab12-ab12-bc34-abcdef123456",
  "resourceId": "+12345612345",
  "resourceType": "ACTIVE_NUMBER",
  "eventType": "PROVISIONING_TO_CAMPAIGN",
  "status": "FAILED",
  "failureCode": "CAMPAIGN_NOT_AVAILABLE"
}

Responses

200 OK