Getting started

This guide will instruct you on how to get started using the Sinch Numbers API. The steps below will walk you through account creation and help you gather the information you'll need to configure the Numbers API for SMS, Voice, or both.

Let's get started!

Account required!

Using the Numbers API requires signing up for an upgraded account on the Sinch Build Dashboard. If you haven't already done so, sign up now and then upgrade your account so you can buy numbers.

1. Get your Project ID and credentials

Get your project ID and create your access key: First, you'll need your project ID and to generate access keys. Access keys are used to authenticate calls when using Numbers API. You can generate access keys and find your project ID in the Sinch Build Dashboard.

You'll need this info later!

Make sure you have your access key, access key secret, and project ID readily available. This information will be required when making any API calls. The access key and access key secret must be recorded during access key creation.

Important!

The access key will be readily visible. The access key secret, however, will only be visible upon new key creation. Create a new key and then save your key secret in a safe place.

You will need both the access key and the access key secret for most endpoints in the Numbers API.

2. Get a number

Now, you're ready to buy your first number.

The following sections contain interactive panels that allow you to complete your API requests on this page. The panels have tabs for setting security, the request body and path and query parameters. For most fields and parameters, if you hover your mouse over the field you can read more context about requirements or accepted values. In most cases, you will need to replace placeholder values with your own values to complete the request.

1
Look up the requirements of the region where you want to buy a number. Both regionCode and numberType are required fields.
Loading...
The region's requirements are included in the response to the API call. These requirements are returned as JSON in the fields object in the body of the response.
Note:
The fields included in the fields object will vary depending on the regionCode and numberType you included in the request body. Ensure you parse through the entire response in order to have a full understanding of the region's requirements.
Some regions may not have number requirements. If you receive a response with Number requirements not found for the region you looked up, that region has no requirements.
2
Look for an available number to buy. When searching for numbers, you can specify the region, number type, and capabilities.
Loading...
Note the number for the next step.
3
If your region does not have any requirements, follow the instructions in the No Requirements tab. Otherwise, follow the instructions in the Requirements tab.
Create your number order. regionCode and numberType are required fields. You can include SMS and Voice configuration if you have an SMS or Voice service already. Enter the available number you want to buy in the numberOrderOption object of the request body.
Loading...
Ensure you copy the number order ID from the response, as you'll need it to submit the number order.
You can now submit your number order. Include the number order ID from the previous step's response in the path of your request.
Note:
Number orders remain reserved for a window of up to 48 hours after creation.
Loading...
Activation of the number is not immediate and you can track the status of order using the order's state property. After the number is activated, it will then be available for use with Sinch products.

Additional resources

Want the whole OpenAPI specification? View it here.

If at any point you need more help, you can find support documentation and answers to frequently asked questions in the Sinch Support Community.