If you want to use the content of this page with an AI tool, or if you are an AI agent, use the Markdown version of this page: https://developers.sinch.com/docs/numbers/getting-started.md
You may also connect to our documentation MCP server by clicking the Connect MCP button:
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!
Using the Numbers API requires signing up for a free account on the Sinch Build Dashboard. If you haven't already done so, sign up now!
Get your project ID and create your access key: First, you'll need your project ID, which can be found in the Sinch Build Dashboard under Setting, then Projects.
Then, create your access key. Access keys are used to authenticate calls when using Numbers API. Access keys are generated in the Sinch Build Dashboard.
Make sure you have your access key, access key secret, and project ID readily available. This information will be required when making the API call to send the text message. The access key and access key secret must be recorded during access key creation. The project ID can be found on the Sinch Build Dashboard's Project Settings page.
The client ID will be readily visible. The secret ID, however, will only be visible upon new key creation. Create a new key and then save your secret ID in a safe place.
You will need both the client ID and the client secret for most endpoints in the Numbers API.
Now, you're ready to buy your first number. There are two ways you can buy a number:
- Buy the first available number based on provided criteria
- Search for an available number and then buy that number.
Select one of the tabs below to see the method you want to use.
The payload, along with instructions on how to populate placeholder variables, is below. Alternatively, each tab features a guide that will walk you through setting up a simple application in the identified coding language (make sure you bring all the information you gathered during this process!):
{
"regionCode": "YOUR_region_code",
"type": "YOUR_type",
"capabilities": [
"SMS"
],
"smsConfiguration": {
"servicePlanId": "YOUR_SMS_servicePlanId",
"campaignId": "YOUR_campaignId_from_TCR"
}
}
This payload will rent the first available number that fits the search criteria you specified and assign (or provision) it to your SMS service plan ID. The placeholder values included in the payload above are detailed in the table below:
Since this guide is intended for testing purposes, you can use your access key and access secret to authenticate using basic authentication, but for production we recommend using a stronger method of authentication, like OAuth 2.0.
| Parameter | Your value |
|---|---|
YOUR_region_code | The two letter abbreviation of the country for which you'd like a number. For example, the United States is US. Should be in ISO 3166-1 alpha-2 format. |
YOUR_type | The type of number you would like to rent. Available options are: MOBILE, LOCAL, or TOLL_FREE. Note that 10DLC numbers should be set to LOCAL. |
YOUR_SMS_servicePlanId | Your SMS service plan ID. This is required for SMS configuration. |
YOUR_campaignId_from_TCR | Only for US phone numbers. This campaignId is required to send SMS traffic to US; click here to read more about 10DLC A2P messaging. So, it is the current campaign ID for this number. The campaignId is found on your TCR platform. |
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.