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 (ImportedNumberResponse)

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.

object

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.

object

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

object

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

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
Found on your Sinch Customer Dashboard. Settings > Projects.


 
 Example:  d1923022-5199-4bb3-a513-c47b3a656bc5
Request Body schema: application/json
required
regionCode
required
string
ISO 3166-1 alpha-2 country code of the phone number. Example US, UK or SE.


 
required
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.


 
campaignId
string
The current campaign ID assigned to this number.


 
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.


 
displayName
string
User supplied name for the phone 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.


 
object
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.


 
object (SmsAtt) 
Contains information about SMS-enabled AT&T numbers.


 
state
string (State) 
Indicates the current state of the operation.


 Enum Value Description
DONE
The operation was completed successfully.


FAILED
The operation has failed.


IN_PROGRESS
The operation is currently in progress.


WAITING
The operation is pending and has not yet started.


STATE_UNSPECIFIED
The state is unspecified.


 
operation
string (Operation) 
Specifies the type of action being performed.


 Enum Value Description
PROVISIONING
The service is being configured or activated.


DEPROVISIONING
The service is being deactivated or removed.


OPERATION_UNSPECIFIED
The operation is unspecified.


 
errorCode
string (ErrorCode) 
An optional string field that contains an error code if the operation failed. This field is empty ("") when there is no error.


 
errorMessage
string (ErrorMessage) 
An optional string field that provides a human-readable message describing the error. This field is empty ("") when no error has occurred.


 
updateTime
string (UpdateTime) 
A timestamp in ISO 8601 format indicating the last time the status was updated.


 
object (SmsTmo) 
Contains information about SMS-enabled T-Mobile numbers.


 
state
string (State) 
Indicates the current state of the operation.


 Enum Value Description
DONE
The operation was completed successfully.


FAILED
The operation has failed.


IN_PROGRESS
The operation is currently in progress.


WAITING
The operation is pending and has not yet started.


STATE_UNSPECIFIED
The state is unspecified.


 
operation
string (Operation) 
Specifies the type of action being performed.


 Enum Value Description
PROVISIONING
The service is being configured or activated.


DEPROVISIONING
The service is being deactivated or removed.


OPERATION_UNSPECIFIED
The operation is unspecified.


 
errorCode
string (ErrorCode) 
An optional string field that contains an error code if the operation failed. This field is empty ("") when there is no error.


 
errorMessage
string (ErrorMessage) 
An optional string field that provides a human-readable message describing the error. This field is empty ("") when no error has occurred.


 
updateTime
string (UpdateTime) 
A timestamp in ISO 8601 format indicating the last time the status was updated.


 
object (MmsAtt) 
Contains information about MMS-enabled AT&T numbers.


 
state
string (State) 
Indicates the current state of the operation.


 Enum Value Description
DONE
The operation was completed successfully.


FAILED
The operation has failed.


IN_PROGRESS
The operation is currently in progress.


WAITING
The operation is pending and has not yet started.


STATE_UNSPECIFIED
The state is unspecified.


 
operation
string (Operation) 
Specifies the type of action being performed.


 Enum Value Description
PROVISIONING
The service is being configured or activated.


DEPROVISIONING
The service is being deactivated or removed.


OPERATION_UNSPECIFIED
The operation is unspecified.


 
errorCode
string (ErrorCode) 
An optional string field that contains an error code if the operation failed. This field is empty ("") when there is no error.


 
errorMessage
string (ErrorMessage) 
An optional string field that provides a human-readable message describing the error. This field is empty ("") when no error has occurred.


 
updateTime
string (UpdateTime) 
A timestamp in ISO 8601 format indicating the last time the status was updated.


 
object (MmsTmo) 
Contains information about MMS-enabled T-Mobile numbers.


 
state
string (State) 
Indicates the current state of the operation.


 Enum Value Description
DONE
The operation was completed successfully.


FAILED
The operation has failed.


IN_PROGRESS
The operation is currently in progress.


WAITING
The operation is pending and has not yet started.


STATE_UNSPECIFIED
The state is unspecified.


 
operation
string (Operation) 
Specifies the type of action being performed.


 Enum Value Description
PROVISIONING
The service is being configured or activated.


DEPROVISIONING
The service is being deactivated or removed.


OPERATION_UNSPECIFIED
The operation is unspecified.


 
errorCode
string (ErrorCode) 
An optional string field that contains an error code if the operation failed. This field is empty ("") when there is no error.


 
errorMessage
string (ErrorMessage) 
An optional string field that provides a human-readable message describing the error. This field is empty ("") when no error has occurred.


 
updateTime
string (UpdateTime) 
A timestamp in ISO 8601 format indicating the last time the status was updated.


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


 
serviceType
string (ServiceType) 
The type of service.


 Enum Value Description
SMS
SMS provisioning.


CAMPAIGN
Campaign provisioning.


 
serviceId
string
A unique identifier for the service being provisioned.


 
type
string (Type) 
Specifies the type of operation. This value of this field is either "PROVISIONING" or "DEPROVISIONING".


 Enum Value Description
PROVISIONING
The operation is provisioning the number.


DEPROVISIONING
The operation is deprovisioning the number.


 
state
string (State) 
Indicates the current state of the operation.


 Enum Value Description
DONE
The operation was completed successfully.


FAILED
The operation has failed.


IN_PROGRESS
The operation is currently in progress.


WAITING
The operation is pending and has not yet started.


STATE_UNSPECIFIED
The state is unspecified.


 
updateTime
string
A timestamp in ISO 8601 format (UTC) indicating the last time the provisioning status was updated.


 
errorMessage
string
If an error occurred during provisioning, this field will contain a descriptive message. It will be an empty string if no error is present.


 
errorCode
string
If an error occurred during provisioning, this field will contain the error code. This field is also an empty string when no error has occurred.


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


 
serviceType
string (ServiceType) 
The type of service.


 Enum Value Description
SMS
SMS provisioning.


CAMPAIGN
Campaign provisioning.


 
serviceId
string
A unique identifier for the service being provisioned.


 
type
string (Type) 
Specifies the type of operation. This value of this field is either "PROVISIONING" or "DEPROVISIONING".


 Enum Value Description
PROVISIONING
The operation is provisioning the number.


DEPROVISIONING
The operation is deprovisioning the number.


 
state
string (State) 
Indicates the current state of the operation.


 Enum Value Description
DONE
The operation was completed successfully.


FAILED
The operation has failed.


IN_PROGRESS
The operation is currently in progress.


WAITING
The operation is pending and has not yet started.


STATE_UNSPECIFIED
The state is unspecified.


 
updateTime
string
A timestamp in ISO 8601 format (UTC) indicating the last time the provisioning status was updated.


 
errorMessage
string
If an error occurred during provisioning, this field will contain a descriptive message. It will be an empty string if no error is present.


 
errorCode
string
If an error occurred during provisioning, this field will contain the error code. This field is also an empty string when no error has occurred.


 
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",
  • "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
Delete an imported number from 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
phoneNumber
required
string
The phone number in E.164 format with leading +.


 
 Example:  +12025550134
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
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
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.


 
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
© 2025 Sinch. All rights reserved.