Some regions have specific requirements that must be fulfilled when purchasing a phone number/sender associated with that region. Sinch's Numbers API allows you to view these requirements, create an order and update it with the appropiate information, and submit the order using multiple chained API calls.
In order to create a number order that meet specific requirements, you must:
- Look up the number requirements for a particular region.
- Look up the number(s) you'd like to order.
- Create the number order.
- Update the number order with the necessary requirements fulfilled. You may also need to upload an attachement, depending on the region's requirements.
- Submit the number order.
The above steps must all be completed by individual API calls that, when chained together, complete the process. The API calls are described in more detail in the subsections below.
Throughout this guide, we use Australia's regional requirements as an example. However, these principles can be applied to any region that has specific requirements that must be fulfilled when purchasing a phone number/sender.
Prior to placing a number order, you must review the requirements of the region. This is done by making a POST call to the numberOrders:lookupNumberRequirements endpoint. The region is defined in the regionCode field and the number type (MOBILE, LOCAL, or TOLL_FREE) is defined in the numberType field. An example payload is below:
{
"regionCode": "AU",
"numberType": "MOBILE"
}
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.
The fields included in the field object will vary depending on the regionCode you included in the request body. Ensure you parse through the entire response in order to have a full understanding of hte region's requirements.
An example response is below:
{
"fields": {
"$schema": "/schema/policySchema-v1.json",
"rules": [
{
"template": {
"$schema": "/schema/assetSchema-v1.json",
"assetType": "SENDER_ID",
"description": "A long number header",
"id": "senderIdMoV1",
"schema": {
"items": {
"properties": {
"iConfirmThatMyBusinessHasAValidUseCaseForThisLn": {
"description": "",
"enum": [
null,
true
],
"title": "I confirm that my business has a valid intended use for this LN.",
"type": "boolean"
},
"intendedUseOfMobileNumbers": {
"description": "Transactional - Automated, time-sensitive messages related to a user's activity or account. These are generally informational and non-promotional. Example: Order confirmations, shipping updates, delivery notifications, payment alerts, booking/reservation confirmations.\nAuthentication & Verification - Messages used for security purposes to confirm user identity or actions. Example: One-Time Passwords (OTPs), Two-Factor Authentication (2FA) codes, account security alerts.\nMarketing & Promotions - Messages designed to promote products, services, special offers, or build customer loyalty. Example: Promotional codes, discounts, new product announcements, flash sales, abandoned cart reminders, event promotions.\nCustomer Service & Conversational - Two-way messaging enabling customers to interact with the business for support or general inquiries. Example: Support ticket updates, feedback requests, general inquiries, customer support conversations.\nInternal Communication - Messages exchanged within an organization for operational purposes. Example: Staff alerts, shift reminders, rostering, internal business updates, employee communication.\nGeneral Alerts & Notifications - Important, non-transactional alerts or announcements that require immediate attention. Example: Emergency alerts, service outage notifications, system maintenance updates, general public notices.",
"enum": [
"Transactional",
"Authentication & Verification",
"Marketing & Promotions",
"Customer Service & Conversational",
"Internal Communication",
"General Alerts & Notifications"
],
"title": "Intended use of mobile number",
"type": "string",
"x-placeholder": ""
},
"purposeOfTheTraffic": {
"description": "",
"enum": [
"One Time Password",
"Transactional",
"Internal communication",
"Content delivery",
"Conversational",
"Marketing"
],
"title": "Purpose of the traffic",
"type": "string"
},
"senderId": {
"title": "Number",
"type": "string"
}
},
"required": [
"purposeOfTheTraffic",
"iConfirmThatMyBusinessHasAValidUseCaseForThisLn",
"intendedUseOfMobileNumbers"
],
"type": "object"
},
"type": "array"
},
"title": "Sender ID Details"
}
},
{
"template": {
"$schema": "/schema/assetSchema-v1.json",
"assetType": "END_USER_COMPANY_DETAILS",
"description": "Used to collect end user company details",
"id": "endUserCompanyDetailsBasicV1",
"schema": {
"properties": {
"city": {
"description": "",
"maxLength": 40,
"messages": {
"maxLength": "City should NOT be longer than 40 characters",
"minLength": "City should NOT be shorter than 1 characters"
},
"minLength": 1,
"multiline": false,
"pattern": ".",
"title": "City",
"type": "string",
"x-placeholder": ""
},
"country": {
"description": "",
"enum": [
"AF",
"AL",
"AN",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BS",
"BH",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BA",
"BW",
"BR",
"BN",
"BG",
"BF",
"BI",
"KH",
"CM",
"CA",
"CV",
"KY",
"CF",
"TD",
"CL",
"CN",
"CO",
"KM",
"CG",
"CD",
"CK",
"CR",
"CI",
"HR",
"CU",
"CY",
"CZ",
"DK",
"IO",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"ET",
"FK",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"XK",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MK",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"YT",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"KP",
"MP",
"NO",
"OM",
"PK",
"PW",
"PS",
"PA",
"PG",
"PY",
"PE",
"PH",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"SK",
"SI",
"SB",
"SO",
"ZA",
"KR",
"SS",
"ES",
"LK",
"SH",
"KN",
"LC",
"PM",
"VC",
"SD",
"SR",
"SZ",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UY",
"UZ",
"VU",
"VE",
"VN",
"VG",
"VI",
"WF",
"YE",
"ZM",
"ZW"
],
"title": "Country",
"type": "string"
},
"endBusinessAddress": {
"description": "",
"maxLength": 25,
"messages": {
"maxLength": "End business address should NOT be longer than 25 characters",
"minLength": "End business address should NOT be shorter than 5 characters"
},
"minLength": 5,
"multiline": false,
"pattern": ".",
"title": "End business address",
"type": "string",
"x-placeholder": ""
},
"endBusinessAddress2": {
"description": "",
"maxLength": 25,
"messages": {
"maxLength": "End business address 2 should NOT be longer than 25 characters",
"minLength": "End business address 2 should NOT be shorter than 5 characters"
},
"minLength": 5,
"multiline": false,
"pattern": ".",
"title": "End business address 2",
"type": "string",
"x-placeholder": ""
},
"endBusinessName": {
"description": "",
"maxLength": 100,
"messages": {
"maxLength": "End business name should NOT be longer than 100 characters",
"minLength": "End business name should NOT be shorter than 5 characters"
},
"minLength": 5,
"multiline": false,
"pattern": ".",
"title": "End business name",
"type": "string"
},
"postalCode": {
"description": "",
"maxLength": 15,
"messages": {
"maxLength": "Postal code should NOT be longer than 15 characters",
"minLength": "Postal code should NOT be shorter than 1 characters"
},
"minLength": 1,
"multiline": false,
"pattern": ".",
"title": "Postal code",
"type": "string"
},
"state": {
"description": "",
"maxLength": 100,
"messages": {
"maxLength": "State should NOT be longer than 100 characters",
"minLength": "State should NOT be shorter than 1 characters"
},
"minLength": 1,
"multiline": false,
"pattern": ".",
"title": "State",
"type": "string",
"x-placeholder": ""
}
},
"required": [
"endBusinessName",
"endBusinessAddress",
"city",
"postalCode",
"state",
"country",
"endBusinessAddress2"
],
"type": "object"
},
"title": "Company Details"
}
},
{
"template": {
"$schema": "/schema/assetSchema-v1.json",
"assetType": "CONTACT",
"description": "A contact person",
"id": "contactPersonNoRequiredV1",
"schema": {
"properties": {
"firstName": {
"description": "",
"maxLength": 40,
"messages": {
"maxLength": "First Name should NOT be longer than 40 characters",
"minLength": "First Name should NOT be shorter than 1 characters",
"pattern": "Needs at least one letter"
},
"minLength": 1,
"multiline": false,
"pattern": "^[A-Za-z0-9 -._]*[A-Za-z][A-Za-z0-9 -._]*$",
"title": "First Name",
"type": "string",
"x-placeholder": ""
},
"lastName": {
"description": "",
"maxLength": 40,
"messages": {
"maxLength": "Last Name should NOT be longer than 40 characters",
"minLength": "Last Name should NOT be shorter than 1 characters",
"pattern": "Needs at least one letter"
},
"minLength": 1,
"multiline": false,
"pattern": "^[A-Za-z0-9 -._]*[A-Za-z][A-Za-z0-9 -._]*$",
"title": "Last Name",
"type": "string",
"x-placeholder": ""
},
"phoneNumber": {
"description": "",
"maxLength": 20,
"messages": {
"maxLength": "Phone Number should NOT be longer than 20 characters",
"minLength": "Phone Number should NOT be shorter than 1 characters",
"pattern": "Needs to be a valid phone number"
},
"minLength": 1,
"multiline": false,
"pattern": "^[\\+][0-9]+$",
"title": "Phone Number",
"type": "string",
"x-placeholder": ""
}
},
"required": [
"firstName",
"lastName",
"phoneNumber"
],
"type": "object"
},
"title": "Contact Person"
}
}
]
},
"attachments": []
}
After you have reviewed the requirements for the region for which you'd like to order a number (or numbers), you must view the available numbers in that region and select the one(s) you intend to order.
Viewing the available numbers is done by making a GET call to the availableNumbers endpoint. The regionCode and type included in the path must be the same as the regionCode and path you included in the call detailed in the Looking up number requirements section. You may detail other number requirements in the body of the call.
The response includes an array of available numbers that match the criteria defined by your call. Each entry includes the phone number itself, the criteria you defined in the call, and other information like pricing and whether or not supporting documentation is required.
An example response is below:
{
"availableNumbers": [
{
"phoneNumber": "+614XXXXXXXX",
"regionCode": "AU",
"type": "MOBILE",
"capability": [
"SMS"
],
"setupPrice": {
"currencyCode": "USD",
"amount": "1.00"
},
"monthlyPrice": {
"currencyCode": "USD",
"amount": "1.00"
},
"paymentIntervalMonths": 1,
"supportingDocumentationRequired": true
},
{
"phoneNumber": "+614YYYYYYYY",
"regionCode": "AU",
"type": "MOBILE",
"capability": [
"SMS"
],
"setupPrice": {
"currencyCode": "USD",
"amount": "1.00"
},
"monthlyPrice": {
"currencyCode": "USD",
"amount": "1.00"
},
"paymentIntervalMonths": 1,
"supportingDocumentationRequired": true
}
]
}
After you have reviewed the requirements for the region for which you'd like to order a number (or numbers), you will create an order for a single number or for multiple numbers. This is done by making a POST call to the numberOrders:createNumberOrder endpoint. Include the numbers you'd like to order in the phoneNumbers sub-array of the numberOrderOption. Alternatively, you can order numbers through pattern-matching by replacing the numberOrderOption array with the quantityOrderOption object.
An example payload is below:
{
"regionCode": "AU",
"numberType": "MOBILE",
"smsConfiguration": {
"servicePlanId": "YOUR_service_plan_ID"
},
"callbackUrl": "www.my-callback-example.com/callback",
"numberOrderOption": {
"phoneNumbers": [
"+614XXXXXXXX"
]
}
}
Immediatley the number order is created, you'll receive a response that includes, among other pieces of information, the ID of the number order. This is included in the idNumberOrder field of the response body, and must be recorded for future API calls. An example response is below:
{
"projectId": "YOUR_project_ID",
"idNumberOrder": "YOUR_order_ID",
"regionCode": "AU",
"state": "CREATED",
"numberType": "MOBILE",
"orderNumbers": [
{
"phoneNumber": "+614XXXXXXXX",
"numberPrice": {
"setupPrice": {
"currencyCode": "USD",
"amount": "1.00"
},
"monthlyPrice": {
"currencyCode": "USD",
"amount": "1.00"
},
"paymentIntervalMonths": 1
},
"capabilities": [
"SMS"
]
}
],
"smsConfiguration": {
"servicePlanId": "YOUR_service_plan_ID"
},
"expireTime": "2026-03-07T16:53:00.204187Z",
"createTime": "2026-03-05T16:53:00Z",
"updateTime": "2026-03-05T16:53:00Z"
}
After creating the number order, you must update the order with the data required by the number's region. This is done by making a PUT call to the registration endpoint. The order is identified in the path variable numberOrderId, which is the number order ID you recorded from the response you received when creating the number order, and the requirements are included in the data object of the call body.
The data object is, essentially, a free-form JSON object that will match the fields included in the respone you received after making the call described in the Looking up number requirements section.
An example payload is below:
{
"data": [
[
{
"senderId": "+614XXXXXXXX",
"purposeOfTheTraffic": "One Time Password",
"intendedUseOfMobileNumbers": "Transactional",
"iConfirmThatMyBusinessHasAValidUseCaseForThisLn": true
}
],
{
"endBusinessName": "YOUR_business_name",
"endBusinessAddress": "YOUR_business_address",
"endBusinessAddress2": "YOUR_second_business_address",
"city": "Victoria",
"state": "VIC",
"country": "AU",
"postalCode": "3000"
},
{
"firstName": "YOUR_business_contact_first_name",
"lastName": "YOUR_business_contact_last_name",
"phoneNumber": "YOUR_business_contact_phone_number"
}
]
}
Some regions may require you to actually upload an attachement. To do so, make a POST call to the attachments/{attachmentId} endpoint. The required attachment IDs can be retrieved using the dedicated number order registration endpoint. The order is identified in the path variable numberOrderId, which is the number order ID you recorded from the response you received when creating the number order.
The upload itself is included in the request body. The request body for this call is multipar/form-data, and the file is included as a MIME type application/vnd.openxmlformats-officedocument.wordprocessingml.document string.
After updating the number order with the required information (and uploading any files, if required), you must submit the number order. This is done by making a POST call to the {numberOrderId}/submit endpoint. The order is identified in the path variable numberOrderId, which is the number order ID you recorded from the response you received when creating the number order.
Upon submitting the number order, Sinch will begin processing the request.