# Ordering numbers that meet specific requirements 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: 1. [Look up the number requirements for a particular region](#looking-up-number-requirements). 2. [Look up the number(s) you'd like to order](#searching-for-numbers). 3. [Create the number order](#creating-the-number-order). 4. [Update the number order with the necessary requirements fulfilled](#updating-the-number-order). You may also need to [upload an attachement](#uploading-an-attachement), depending on the region's requirements. 5. [Submit the number order](#submitting-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. Note: 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. ## Looking up number requirements 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](/docs/numbers/api-reference/numbers/number-order/lookupnumberrequirements). 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: ```JSON { "regionCode": "AU", "numberType": "MOBILE" } ``` ### Understanding the response 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 `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: ```JSON { "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": [] } ``` ## Searching for numbers 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](/docs/numbers/api-reference/numbers/available-number/numberservice_listavailablenumbers). 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](#looking-up-number-requirements) section. You may detail other number requirements in the body of the call. ### Selecting your numbers from the response 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: ```JSON { "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 } ] } ``` ## Creating the number order 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](/docs/numbers/api-reference/numbers/number-order/createnumberorder). 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: ```JSON { "regionCode": "AU", "numberType": "MOBILE", "smsConfiguration": { "servicePlanId": "YOUR_service_plan_ID" }, "callbackUrl": "www.my-callback-example.com/callback", "numberOrderOption": { "phoneNumbers": [ "+614XXXXXXXX" ] } } ``` ### Recording the number order ID 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: ```JSON { "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" } ``` ## Updating the number order 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](/docs/numbers/api-reference/numbers/number-order/updatenumberorderregistration). 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](#recording-the-number-order-id), 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](#understanding-the-response) after making the call described in the [Looking up number requirements](#looking-up-number-requirements) section. An example payload is below: ```JSON { "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" } ] } ``` ### Uploading an attachement Some regions may require you to actually upload an attachement. To do so, make a [`POST` call to the `attachments/{attachmentId}` endpoint](/docs/numbers/api-reference/numbers/number-order/uploadnumberorderattachment). The required attachment IDs can be retrieved using the [dedicated number order registration endpoint](/docs/numbers/api-reference/numbers/number-order/getnumberorderregistration). 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](#recording-the-number-order-id). 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. ## Submitting the number order 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](/docs/numbers/api-reference/numbers/number-order/submitnumberorder). 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](#recording-the-number-order-id). Upon submitting the number order, Sinch will begin processing the request.