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.

List imported numbers

Lists all imported numbers for the project.

SecurityBasic or OAuth2.0
Request
path Parameters
projectId
required
string

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: d1923022-5199-4bb3-a513-c47b3a656bc5
query Parameters
servicePlanId
required
string

The hosting order servicePlanId

Example: servicePlanId=324e4567-e89b-12d3-a456-426614174000
campaignId
required
string

The hosting order campaignId

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

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.pattern
string

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.searchPattern
string

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: "START" "CONTAIN" "END"
Example: numberPattern.searchPattern=START
pageSize
integer

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

Example: pageSize=20
pageToken
string

The next page token value returned from a previous listing.

Example: pageToken=C2VNYXJrEg4KDCsxMjAxMjI2MzUyOQ==
orderBy
string

Parameter used to order the returned hosting orders

Responses
200

OK

Response Schema: application/json
Array of objects (ImportedNumber)

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

Array
phoneNumber
string

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

projectId
string

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

regionCode
string

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

displayName
string

User supplied name for the phone number.

object (SmsConfiguration)

Configuration for SMS

callbackUrl
string

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

nextPageToken
string

The token to be used for listing the next page.

totalSize
400

If the page_token, number_pattern or order_by is not valid.

500

INTERNAL: Internal server error. Typically, a server bug.

get/v1/projects/{projectId}/importedNumbers
Request samples 
Response samples 
application/json
{
  • "importedNumbers": [
    • {
      }
    ],
  • "nextPageToken": "string",
  • "totalSize": 0
}
Import number
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)?


SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The ID of the project resource. You can find your project ID on dashboard.sinch.com.


 
Request Body schema: application/json
required
phoneNumber
string
The phone number in e.164 format with leading +.


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


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


 
displayName
string
User supplied name for the phone number.


 
object (SmsConfiguration) 
Configuration for SMS


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


 
object (ScheduledProvisioning) 
Ongoing Provisioning for SMS service


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
integer <enum> 
Status of the pending change.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
The campaign of the scheduled provisioning task.


 
errorCodes
Array of integers <enum> 
A list of error codes, if applicable, for the scheduled provisioning task.


 
campaignId
string
The current campaign ID assigned to this number.


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


 
Responses 
200
OK


Response Schema: application/json
phoneNumber
string
The phone number in e.164 format with leading +.


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


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


 
displayName
string
User supplied name for the phone number.


 
object (SmsConfiguration) 
Configuration for SMS


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


 
object (ScheduledProvisioning) 
Ongoing Provisioning for SMS service


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
integer <enum> 
Status of the pending change.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
The campaign of the scheduled provisioning task.


 
errorCodes
Array of integers <enum> 
A list of error codes, if applicable, for the scheduled provisioning task.


 
campaignId
string
The current campaign ID assigned to this number.


 
migrateToSinchTmo
boolean
Displays if a number is assigned to another aggregator in T-Mobile's platform, and requires migration from previous aggregator to Sinch.


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


 
400
INVALID_ARGUMENT: If the importedNumber.phoneNumber, importedNumber.smsConfiguration.servicePlanId is not valid.


409
The imported number already exists.


500
INTERNAL: Internal server error. Typically, a server bug.


post/v1/projects/{projectId}/importedNumbers
Request samples 
application/json
{
  • "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"
}
Response samples 
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
Returns the imported number you specify in the path.


SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
Found on your Sinch Customer Dashboard. Settings > Projects.


 
 Example:  d1923022-5199-4bb3-a513-c47b3a656bc5
phoneNumber
required
string
The phone number in E.164 format with leading +.


 
 Example:  +12025550134
Responses 
200
OK


Response Schema: application/json
phoneNumber
string
The phone number in e.164 format with leading +.


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


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


 
displayName
string
User supplied name for the phone number.


 
object (SmsConfiguration) 
Configuration for SMS


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


 
object (ScheduledProvisioning) 
Ongoing Provisioning for SMS service


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
integer <enum> 
Status of the pending change.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
The campaign of the scheduled provisioning task.


 
errorCodes
Array of integers <enum> 
A list of error codes, if applicable, for the scheduled provisioning task.


 
campaignId
string
The current campaign ID assigned to this number.


 
migrateToSinchTmo
boolean
Displays if a number is assigned to another aggregator in T-Mobile's platform, and requires migration from previous aggregator to Sinch.


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


 
404
The imported number could not be found.


500
INTERNAL: Internal server error. Typically, a server bug.


get/v1/projects/{projectId}/importedNumbers/{phoneNumber}
Request samples 
Response samples 
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"
}
Delete imported number
Delete an imported number from the project.


SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The ID of the project resource. You can find your project ID on dashboard.sinch.com.


 
phoneNumber
required
string
The imported phone number to release.


 
Responses 
200
OK


404
The imported number could not be found.


500
INTERNAL: Internal server error. Typically, a server bug.


delete/v1/projects/{projectId}/importedNumbers/{phoneNumber}
Request samples 
Response samples 
application/json
{
  • "code": "404",
  • "message": "The imported number could not be found.",
  • "status": "NOT_FOUND"
}
Update imported number
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.
    • 



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The ID of the project resource.


 
phoneNumber
required
string
The phone number in e.164 format with leading +.


 
query Parameters
updateMask
string <field-mask> 
FieldMask that determines which resource fields are modified in an update. Following fields can be updated:


    

  • displayName
    • 

  • smsConfiguration.servicePlanId
    • 



 
Request Body schema: application/json
required
phoneNumber
string
The phone number in e.164 format with leading +.


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


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


 
displayName
string
User supplied name for the phone number.


 
object (SmsConfiguration) 
Configuration for SMS


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


 
object (ScheduledProvisioning) 
Ongoing Provisioning for SMS service


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
integer <enum> 
Status of the pending change.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
The campaign of the scheduled provisioning task.


 
errorCodes
Array of integers <enum> 
A list of error codes, if applicable, for the scheduled provisioning task.


 
campaignId
string
The current campaign ID assigned to this number.


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


 
Responses 
200
OK


Response Schema: application/json
phoneNumber
string
The phone number in e.164 format with leading +.


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


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


 
displayName
string
User supplied name for the phone number.


 
object (SmsConfiguration) 
Configuration for SMS


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


 
object (ScheduledProvisioning) 
Ongoing Provisioning for SMS service


 
servicePlanId
string
Service plan of the scheduled provisioning task.


 
status
integer <enum> 
Status of the pending change.


 
lastUpdatedTime
string <date-time> 
Timestamp when the status was last updated.


 
campaignId
string
The campaign of the scheduled provisioning task.


 
errorCodes
Array of integers <enum> 
A list of error codes, if applicable, for the scheduled provisioning task.


 
campaignId
string
The current campaign ID assigned to this number.


 
migrateToSinchTmo
boolean
Displays if a number is assigned to another aggregator in T-Mobile's platform, and requires migration from previous aggregator to Sinch.


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


 
400
INVALID_ARGUMENT: If the fieldMask is not provided or importedNumber.smsConfiguration.servicePlanId is not valid.


404
The imported number could not be found.


500
INTERNAL: Internal server error. Typically, a server bug.


patch/v1/projects/{projectId}/importedNumbers/{phoneNumber}
Request samples 
application/json
{}
Response samples 
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"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.