Skip to content
Numbers/
/
/
List imported numbers

Imported Numbers and Hosting Orders (1.0)

API for importing, hosting, and qualifying numbers to enable them for use with Sinch SMS text messaging services.

Download OpenAPI description
imported-hosting.json
imported-hosting.yaml
Overview
URL

https://www.sinch.com

Support

support@sinch.com

License

MIT

Languages
Servers
Global API

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

Hosting Orders

Hosted numbers provide you with an easy method to port your SMS enabled numbers to Sinch or to use SMS messaging and other products to send and receive messages, on voice-enabled numbers (including landline numbers) that you already own.

Note: The SMS enablement process is only supported in United States and Canada.

The Hosting Orders API allows you to manage all the numbers that you are hosting on the Sinch platform. This includes numbers that you have ported to Sinch and/or any non- Sinch numbers that you already own and are hosting on Sinch to enable Sinch SMS messaging and other products.

Operations

Imported Numbers

Use the Imported Numbers API endpoints to list imported numbers or import a number that's already been provisioned with an NNID for use with Sinch. Imported numbers can be used with Sinch SMS services.

Note: The SMS enablement process is only supported in United States and Canada.

Operations

List imported numbers

Request

Lists all imported numbers for the project.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: d1923022-5199-4bb3-a513-c47b3a656bc5
Query
servicePlanIdstringrequired

The hosting order servicePlanId

Example: servicePlanId=324e4567-e89b-12d3-a456-426614174000
campaignIdstringrequired

The hosting order campaignId

Example: campaignId=123e4567-e89b-12d3-a456-426614174000
regionCodestring

Region code to filter by. ISO 3166-1 alpha-2 country code of the phone number. Currently supported are US, CA

Example: regionCode=US
numberPattern.patternstring

Sequence of digits to search for. If you prefer or need certain digits in sequential order, you can enter the sequence of numbers here. When using START, a plus sign (+) must be included and URL encoded. For example, to search for area code 206 in the US, the url encoded string would be %2B1206

Example: numberPattern.pattern=+1732
numberPattern.searchPatternstring

Search pattern to apply. The options are, START, CONTAIN, and END. Numbers that begin with the numberPattern.pattern entered. Often used to search for a specific area code.

Enum ValueDescription
START

Number starts with specified pattern.

CONTAIN

Number contains specified pattern.

END

Number ends with specified pattern.

Example: numberPattern.searchPattern=START
pageSizeinteger

The maximum number of items to return, server can enforce an upper limit and overwrite the value.

Example: pageSize=20
pageTokenstring

The next page token value returned from a previous listing.

Example: pageToken=C2VNYXJrEg4KDCsxMjAxMjI2MzUyOQ==
orderBystring

Parameter used to order the returned hosting orders

Enum ValueDescription
createdTime

Order by the time the hosting order was created.

updatedTime

Order by the time the hosting order was last updated.

curl -i -X GET \
  -u <username>:<password> \
  'https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/importedNumbers?servicePlanId=324e4567-e89b-12d3-a456-426614174000&campaignId=123e4567-e89b-12d3-a456-426614174000&regionCode=US&numberPattern.pattern=%2B1732&numberPattern.searchPattern=START&pageSize=20&pageToken=C2VNYXJrEg4KDCsxMjAxMjI2MzUyOQ%3D%3D&orderBy=createdTime'

Responses

OK

Bodyapplication/json
importedNumbersArray of objects(ImportedNumberResponse)

List of numbers associated to the client project specified in ListImportedNumbers.

nextPageTokenstring

The token to be used for listing the next page.

totalSizeinteger(int32)

https://cloud.google.com/apis/design/design_patterns#list_pagination

Response
application/json
{
  "importedNumbers": [
    { … }
  ],
  "nextPageToken": "string",
  "totalSize": 0
}

Import number

Request

You can use the Import Numbers API to import a non-Sinch number that you want to enable for SMS with Sinch as the Direct Connectivity Aggregator (DCA) without porting (or even partially porting) the number.

Note: Customers who are importing numbers (i.e. want to use their own NNID) will need to complete the NNID provisioning process to support proper message routing with the carriers. To learn more, refer to the article How can you provision a Network Number ID (NNID)?

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: d1923022-5199-4bb3-a513-c47b3a656bc5
Bodyapplication/jsonrequired
regionCodestringrequired

ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.

Example: "US"
smsConfigurationobject(SmsConfiguration)required

Configuration for SMS

smsConfiguration.​servicePlanIdstring

The current SMS configuration for this number. The `servicePlanId`` can be found when logging into dashboard.sinch.com in the SMS>APIs section.

Example: "YOUR_service_plan_id"
smsConfiguration.​campaignIdstring

The current campaign ID assigned to this number.

Example: "YOUR_campaign_id"
phoneNumberstring

The phone number in e.164 format with leading +.

Example: "+12025550134"
projectIdstring

The ID of the project resource. You can find your project ID on dashboard.sinch.com.

Example: "YOUR_project_id"
displayNamestring

User supplied name for the phone number.

Example: "MyPhoneNumber"
callbackUrlstring

The client's callback URL to be called upon finishing the number import.

Example: "https://www.your-callback-server.com/callback"
curl -i -X POST \
  -u <username>:<password> \
  https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/importedNumbers \
  -H 'Content-Type: application/json' \
  -d '{
    "regionCode": "US",
    "smsConfiguration": {
      "servicePlanId": "YOUR_service_plan_id",
      "campaignId": "YOUR_campaign_id",
      "migrateToSinchTmo": true
    },
    "phoneNumber": "+11234567890",
    "displayName": "MyPhoneNumber",
    "callbackUrl": "https://www.your-callback-server.com/callback"
  }'

Responses

OK

Bodyapplication/json
phoneNumberstring

The phone number in e.164 format with leading +.

Example: "+12025550134"
projectIdstring

The ID of the project resource. You can find your project ID on dashboard.sinch.com.

Example: "YOUR_project_id"
regionCodestring

ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.

Example: "US"
displayNamestring

User supplied name for the phone number.

Example: "MyPhoneNumber"
smsConfigurationobject(SmsConfiguration)

Configuration for SMS

callbackUrlstring

The client's callback URL to be called upon finishing the number import.

Example: "https://www.your-callback-server.com/callback"
Response
application/json
{
  "phoneNumber": "+12025550134",
  "projectId": "YOUR_project_id",
  "regionCode": "US",
  "displayName": "MyPhoneNumber",
  "smsConfiguration": {
    "servicePlanId": "YOUR_service_plan_id",
    "scheduledProvisioning": { … },
    "campaignId": "YOUR_campaign_id",
    "migrateToSinchTmo": true
  },
  "callbackUrl": "https://www.your-callback-server.com/callback"
}

Get imported number

Request

Returns the imported number you specify in the path.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: d1923022-5199-4bb3-a513-c47b3a656bc5
phoneNumberstringrequired

The phone number in E.164 format with leading +.

Example: +12025550134
curl -i -X GET \
  -u <username>:<password> \
  'https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/importedNumbers/+12025550134'

Responses

OK

Bodyapplication/json
phoneNumberstring

The phone number in e.164 format with leading +.

Example: "+12025550134"
projectIdstring

The ID of the project resource. You can find your project ID on dashboard.sinch.com.

Example: "YOUR_project_id"
regionCodestring

ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.

Example: "US"
displayNamestring

User supplied name for the phone number.

Example: "MyPhoneNumber"
smsConfigurationobject(SmsConfiguration)

Configuration for SMS

callbackUrlstring

The client's callback URL to be called upon finishing the number import.

Example: "https://www.your-callback-server.com/callback"
mnoConfigurationobject

The mnoConfiguration object represents the status and progress of configuration operations for SMS and MMS services across different carriers (AT&T and T-Mobile). Each key within this object (smsAtt, smsTmo, mmsAtt and mmsTmo) corresponds to a specific service type (SMS or MMS) associated with a particular mobile network operator.

smsProvisioningobject

An object giving details about the SMS provisioning of the number.

campaignProvisioningobject

An object giving details about the campaign provisioning of the number.

Response
application/json
{
  "phoneNumber": "+12025550134",
  "projectId": "YOUR_project_id",
  "regionCode": "US",
  "displayName": "MyPhoneNumber",
  "smsConfiguration": {
    "servicePlanId": "YOUR_service_plan_id",
    "scheduledProvisioning": { … },
    "campaignId": "YOUR_campaign_id",
    "migrateToSinchTmo": true
  },
  "callbackUrl": "https://www.your-callback-server.com/callback",
  "mnoConfiguration": {
    "smsAtt": { … },
    "smsTmo": { … },
    "mmsAtt": { … },
    "mmsTmo": { … }
  },
  "smsProvisioning": {
    "serviceType": "SMS",
    "serviceId": "0130a21c9ed6461ba3a1fefda83f7ec7",
    "type": "PROVISIONING",
    "state": "DONE",
    "updateTime": "2023-02-02T21:00:07.467353Z",
    "errorMessage": "",
    "errorCode": ""
  },
  "campaignProvisioning": {
    "serviceType": "SMS",
    "serviceId": "CDCQLGJ",
    "type": "PROVISIONING",
    "state": "DONE",
    "updateTime": "2023-02-02T21:00:07.467353Z",
    "errorMessage": "",
    "errorCode": ""
  }
}

Delete imported number

Request

Delete an imported number from the project.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: d1923022-5199-4bb3-a513-c47b3a656bc5
phoneNumberstringrequired

The phone number in E.164 format with leading +.

Example: +12025550134
curl -i -X DELETE \
  -u <username>:<password> \
  'https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/importedNumbers/+12025550134'

Responses

OK

Body
Response
No content

Update imported number

Request

Update an imported phone number. You can perform the following updates:

  • Update the name that displays for a customer by modifying the displayName parameter.
  • Unlink the number from an SMS service or campaign by updating the smsConfiguration configuration object. To unlink a number, submit the request with an empty string (””) in the service plan ID or campaign ID fields.
  • Before linking a number to a new service or campaign, it must be unlinked from any existing service or campaign. Then, link the number to a new SMS service or campaign by updating the service plan ID or campaign ID with the new desired value.
Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: d1923022-5199-4bb3-a513-c47b3a656bc5
phoneNumberstringrequired

The phone number in E.164 format with leading +.

Example: +12025550134
Bodyapplication/jsonrequired
phoneNumberstring

The phone number in e.164 format with leading +.

Example: "+12025550134"
projectIdstring

The ID of the project resource. You can find your project ID on dashboard.sinch.com.

Example: "YOUR_project_id"
regionCodestring

ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.

Example: "US"
displayNamestring

User supplied name for the phone number.

Example: "MyPhoneNumber"
smsConfigurationobject(SmsConfiguration)

Configuration for SMS

callbackUrlstring

The client's callback URL to be called upon finishing the number import.

Example: "https://www.your-callback-server.com/callback"
curl -i -X PATCH \
  -u <username>:<password> \
  'https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/importedNumbers/+12025550134' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "My Display Name",
    "smsConfiguration": {
      "servicePlanId": "",
      "campaignId": ""
    },
    "callbackUrl": "https://www.your-callback-server.com/callback"
  }'

Responses

OK

Bodyapplication/json
phoneNumberstring

The phone number in e.164 format with leading +.

Example: "+12025550134"
projectIdstring

The ID of the project resource. You can find your project ID on dashboard.sinch.com.

Example: "YOUR_project_id"
regionCodestring

ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.

Example: "US"
displayNamestring

User supplied name for the phone number.

Example: "MyPhoneNumber"
smsConfigurationobject(SmsConfiguration)

Configuration for SMS

callbackUrlstring

The client's callback URL to be called upon finishing the number import.

Example: "https://www.your-callback-server.com/callback"
Response
application/json
{
  "phoneNumber": "+12025550134",
  "projectId": "YOUR_project_id",
  "regionCode": "US",
  "displayName": "MyPhoneNumber",
  "smsConfiguration": {
    "servicePlanId": "YOUR_service_plan_id",
    "scheduledProvisioning": { … },
    "campaignId": "YOUR_campaign_id",
    "migrateToSinchTmo": true
  },
  "callbackUrl": "https://www.your-callback-server.com/callback"
}

Qualified Numbers

You can use the Qualified Numbers API to qualify numbers you want Sinch to host and have available for use with Sinch SMS services. Qualifying a number involves verifying ownership of a number either by providing a one time passcode sent to the number by voice call or by providing invoices for multiple numbers. Once numbers are qualified, you can then enable those numbers for SMS text messaging services.

Note: The SMS enablement process is only supported in United States and Canada.

Operations

Imported Numbers and Hosting Orders 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