Skip to content
Numbers/
/
/
Text enable Toll Free num...

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

List hosting orders

Request

Lists the hosting orders 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
statesstringrequired

The hosting order states

Enum ValueDescription
HOSTING_ORDER_STATE_UNSPECIFIED

State is unspecified.

DRAFT

Hosting order is a draft.

SUBMITTED

Hosting order has been submitted.

WAITING_FOR_LOA_SIGNATURE

Hosting order is waiting for the LoA signature.

IN_PROGRESS

Hosting order is in progress.

COMPLETED

Hosting order is completed.

REJECTED

Hosting order is rejected.

typestringrequired

The hosting order type

Enum ValueDescription
HOSTING_ORDER_TYPE_UNSPECIFIED

Type is unspecified.

IMPORT

Type is importing numbers.

TYPE_TEXT_ENABLE

Type is text enabling numbers.

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

pageTokenstring

The next page token value returned from a previous listing.

Example: pageToken=C2VNYXJrEg4KDCsxMjAxMjI2MzUyOQ==
pageSizeinteger

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

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

Responses

OK

Bodyapplication/json
hostingOrdersArray of objects(HostingOrder)
nextPageTokenstring
totalSizeinteger(int32)
Response
application/json
{
  "hostingOrders": [
    { … }
  ],
  "nextPageToken": "string",
  "totalSize": 0
}

Get hosting order

Request

Returns the hosting order specified by the hosting order ID.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

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

Found on your Sinch Customer Dashboard. Settings > Projects.

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

Responses

OK

Bodyapplication/json
projectIdstring

The project ID to which the hosting order is associated.

Example: "YOUR_project_id"
hostingOrderIdstring

The unique ID of the hosting order.

Example: "YOUR_hosting_order_id"
displayNamestring

The friendly name of the hosting order.

Example: "MyHostingOrder"
regionCodestring

The region code of the hosting order. Number hosting is only available for the US and Canada, so you must enter either "US" or "CA".

Example: "US"
statestring

The state of the hosting order.

Enum ValueDescription
HOSTING_ORDER_STATE_UNSPECIFIED

State is unspecified.

DRAFT

Hosting order is a draft.

SUBMITTED

Hosting order has been submitted.

WAITING_FOR_LOA_SIGNATURE

Hosting order is waiting for the LoA signature.

IN_PROGRESS

Hosting order is in progress.

COMPLETED

Hosting order is completed.

REJECTED

Hosting order is rejected.

typestring

The hosting order type.

Enum ValueDescription
HOSTING_ORDER_TYPE_UNSPECIFIED

The type of hosting order is unspecified.

IMPORT

Hosting order to import numbers.

TYPE_TEXT_ENABLE

Hosting order to text-enable numbers.

createdTimestring(date-time)read-only

Timestamp when the hosting order was created

updatedTimestring(date-time)read-only

Timestamp when the hosting order was last updated

scheduledOsrUpdateTimestring(date-time)read-only

Timestamp when the OSR update will be done

servicePlanIdstring

The service plan to which the hosting order is associated.

Example: "YOUR_service_plan_id"
campaignIdstring

The campaign to which the hosting order is associated.

Example: "YOUR_campaign_id"
migrateToSinchTmobooleanread-only

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

textEnableInfoobject(TextEnableInfo)
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
{
  "projectId": "d1923022-5199-4bb3-a513-c47n7a656bc5",
  "hostingOrderId": "01arz3nhyrtsv4rrffq69g5fav",
  "displayName": "Hosting order with campaignId, nnid and smsAppId",
  "regionCode": "US",
  "state": "SUBMITTED",
  "type": "IMPORT",
  "createdTime": "2023-01-12T14:34:40.968Z",
  "updatedTime": "2023-01-12T14:34:40.968Z",
  "scheduledOsrUpdateTime": "2023-01-13T14:34:40.968Z",
  "servicePlanId": "16e5c8d2odc842bda9a1b90e1673c174",
  "campaignId": "C3O84GA",
  "migrateToSinchTmo": true,
  "callbackUrl": "https://www.your-callback-server.com/callback",
  "hostingOrderInfo": {
    "businessName": "Sinch AB",
    "authorisedPerson": { … },
    "address": { … },
    "serviceProvider": "Sinch America Inc.",
    "currentVoiceCarrier": "Verizon",
    "nnid": "104029",
    "loaType": "DIRECT"
  }
}

Retrieve a hosting order report

Request

Returns the report object for a specific hosting order

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

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

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: 01arz3ndektsv4rrffq69g5fav
curl -i -X GET \
  -u <username>:<password> \
  https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/hostingOrders/01arz3ndektsv4rrffq69g5fav/report

Responses

A successful response with a hosting order report, or an error

Bodyapplication/json
totalinteger(int32)
osrUpdatedinteger(int32)
smsProvisionedinteger(int32)
addedToCampaigninteger(int32)
ongoingManualActioninteger(int32)
Response
application/json
{
  "total": 1,
  "osrUpdated": 1,
  "smsProvisioned": 1,
  "addedToCampaign": 1
}

List hosting order numbers

Request

Lists the numbers belonging to the specified hosting order.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

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

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: 01arz3ndektsv4rrffq69g5fav
Query
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.

pageTokenstring

The next page token value returned from a previous listing.

Example: pageToken=C2VNYXJrEg4KDCsxMjAxMjI2MzUyOQ==
pageSizeinteger

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

Example: pageSize=20
osrUpdateStatestring(State)

Filter the results by the state of the OSR update.

Enum ValueDescription
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.

Example: osrUpdateState=DONE
campaignProvisioningStatestring(State)

Filter the results by the state of the campaign provisioning.

Enum ValueDescription
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.

Example: campaignProvisioningState=DONE
platformProvisioningStatestring(State)

Filter the results by the state of the platform provisioning.

Enum ValueDescription
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.

Example: platformProvisioningState=DONE
curl -i -X GET \
  -u <username>:<password> \
  'https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/hostingOrders/01arz3ndektsv4rrffq69g5fav/numbers?orderBy=createdTime&pageToken=C2VNYXJrEg4KDCsxMjAxMjI2MzUyOQ%3D%3D&pageSize=20&osrUpdateState=DONE&campaignProvisioningState=DONE&platformProvisioningState=DONE'

Responses

OK

Bodyapplication/json
numbersArray of objects(HostingOrderNumber)
nextPageTokenstring
totalSizeinteger(int32)
Response
application/json
{
  "numbers": [
    { … }
  ],
  "nextPageToken": "string",
  "totalSize": 0
}

Get hosting order number

Request

Returns the specified phone number belonging to the specified hosting order.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

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

Found on your Sinch Customer Dashboard. Settings > Projects.

Example: 01arz3ndektsv4rrffq69g5fav
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/hostingOrders/01arz3ndektsv4rrffq69g5fav/numbers/+12025550134'

Responses

OK

Bodyapplication/json
projectIdstring

The project ID to which the number belongs.

Example: "YOUR_project_id"
hostingOrderIdstring

The ID of the hosting order to which the number belongs.

Example: "YOUR_hosting_order_id"
phoneNumberstring

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

Example: "+12025550134"
osrUpdateobject(HostingOrderNumber_OsrUpdate)

An object containing information about the OSR update.

campaignProvisioningobject(HostingOrderNumber_CampaignProvisioning)

An object containing information about campaign provisioning.

platformProvisioningobject(HostingOrderNumber_PlatformProvisioning)

An object containing information related to the provisioning on the platform.

smsAttobject

Contains information about hosted SMS AT&T numbers.

smsTmoobject

Contains information about hosted SMS T-Mobile numbers.

mmsAttobject

Contains information about hosted MMS AT&T numbers.

mmsTmoobject

Contains information about hosted MMS T-Mobile numbers.

Response
application/json
{
  "projectId": "YOUR_project_id",
  "hostingOrderId": "YOUR_hosting_order_id",
  "phoneNumber": "+12025550134",
  "osrUpdate": {
    "nnid": "string",
    "state": "DONE"
  },
  "campaignProvisioning": {
    "campaignId": "YOUR_campaign_id",
    "state": "DONE"
  },
  "platformProvisioning": {
    "servicePlanId": "YOUR_service_plan_id",
    "state": "DONE"
  },
  "smsAtt": {
    "state": "DONE",
    "errorCode": "",
    "errorMessage": "string",
    "updateTime": "2025-04-02T19:45:28.650924Z"
  },
  "smsTmo": {
    "state": "DONE",
    "errorCode": "",
    "errorMessage": "string",
    "updateTime": "2025-04-02T19:45:28.650924Z"
  },
  "mmsAtt": {
    "state": "DONE",
    "errorCode": "",
    "errorMessage": "string",
    "updateTime": "2025-04-02T19:45:28.650924Z"
  },
  "mmsTmo": {
    "state": "DONE",
    "errorCode": "",
    "errorMessage": "string",
    "updateTime": "2025-04-02T19:45:28.650924Z"
  }
}

Import numbers using hosting orders

Request

Import numbers associated with hosting orders of a specific project and schedule the async provisioning to Sinch SMS platform and linking to campaign if applicable.

Note: This operation is limited to five numbers. If you want to increase the quantity of numbers you can import using this operation, please contact your account manager for authorization.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

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

The request to import hosting orders numbers in the current project

regionCodestringrequired

The region code for the import request.

Example: "US"
numbersArray of stringsrequired

An array of all the phone numbers associated with the import request.

Example: ["+12025550134"]
servicePlanIdstringrequired

The ID of the service plan to which the import request is associated.

Example: "YOUR_service_plan_id"
projectIdstring

The ID of the project to which the import request is associated.

Example: "YOUR_project_id"
displayNamestring

The optional display name of the import request.

Example: "MyImportRequest"
campaignIdstring

The ID of the campaign to which the request is associated.

Example: "YOUR_campaign_id"
callbackUrlstring

The callback URL to be called for import numbers updates

migrateToSinchTmoboolean

If a number is assigned to another aggregator in T-Mobile's platform, then T-Mobile will give an error code 60135 indicating that number needs to be “migrated” from previous aggregator to Sinch. This “migration” requires provisioning of number by setting this flag named to true for successful number linking process.

curl -i -X POST \
  -u <username>:<password> \
  https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/hostingOrders:importNumbers \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "Import numbers order",
    "regionCode": "US",
    "numbers": [
      "+17724295286",
      "+17724295287"
    ],
    "servicePlanId": "07d6c2621f364b68856fe4938b7bb78f",
    "campaignId": "C3O8OGA",
    "callbackUrl": "https://www.your-callback-server.com/callback",
    "migrateToSinchTmo": true
  }'

Responses

A successful response with a hosting order, or an error

Bodyapplication/json
projectIdstring

The project ID to which the hosting order is associated.

Example: "YOUR_project_id"
hostingOrderIdstring

The unique ID of the hosting order.

Example: "YOUR_hosting_order_id"
displayNamestring

The friendly name of the hosting order.

Example: "MyHostingOrder"
regionCodestring

The region code of the hosting order. Number hosting is only available for the US and Canada, so you must enter either "US" or "CA".

Example: "US"
statestring

The state of the hosting order.

Enum ValueDescription
HOSTING_ORDER_STATE_UNSPECIFIED

State is unspecified.

DRAFT

Hosting order is a draft.

SUBMITTED

Hosting order has been submitted.

WAITING_FOR_LOA_SIGNATURE

Hosting order is waiting for the LoA signature.

IN_PROGRESS

Hosting order is in progress.

COMPLETED

Hosting order is completed.

REJECTED

Hosting order is rejected.

typestring

The hosting order type.

Enum ValueDescription
HOSTING_ORDER_TYPE_UNSPECIFIED

The type of hosting order is unspecified.

IMPORT

Hosting order to import numbers.

TYPE_TEXT_ENABLE

Hosting order to text-enable numbers.

createdTimestring(date-time)read-only

Timestamp when the hosting order was created

updatedTimestring(date-time)read-only

Timestamp when the hosting order was last updated

servicePlanIdstring

The service plan to which the hosting order is associated.

Example: "YOUR_service_plan_id"
campaignIdstring

The campaign to which the hosting order is associated.

Example: "YOUR_campaign_id"
migrateToSinchTmobooleanread-only

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

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
{
  "projectId": "d1923022-5199-4bb3-a513-c47n7a656bc5",
  "hostingOrderId": "01arz3nhyrtsv4rrffq69g5fav",
  "displayName": "Hosting order with campaignId and smsAppId",
  "regionCode": "US",
  "state": "SUBMITTED",
  "type": "IMPORT",
  "createdTime": "2023-01-12T14:34:40.968Z",
  "updatedTime": "2023-01-12T14:34:40.968Z",
  "servicePlanId": "16e5c8d2odc842bda9a1b90e1673c174",
  "campaignId": "C3O84GA",
  "migrateToSinchTmo": true,
  "callbackUrl": "https://www.your-callback-server.com/callback",
  "numberImport": "{}"
}

Text enable numbers in hosting orders

Request

Text enable numbers associated with hosting orders of a specific project.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

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

The request to text-enable hosting orders numbers in the current project

regionCodestringrequired

The region code for the hosting order.

Example: "US"
numbersArray of stringsrequired

An array of all the phone numbers associated with the hosting order.

Example: ["+12025550134"]
servicePlanIdstringrequired

The ID of the service plan to which the hosting order is associated.

Example: "YOUR_service_plan_id"
projectIdstring

The ID of the project to which the hosting order is associated.

Example: "YOUR_project_id"
displayNamestring

The optional display name of the hosting order.

Example: "MyHostingOrder"
nnidstring

Defaults to either Sinch NNID or what was originally configured on the customer account. Sinch encourages customers to use the Sinch NNID, but if you want to use another NNID, please contact your account manager.

campaignIdstring

The ID of the campaign to which the hosting order is associated.

Example: "YOUR_campaign_id"
directLoaInfoobject(DirectLoaInfo)

Letter of Authorization for direct Sinch customers.

resellerLoaInfoobject(ResellerLoaInfo)

Letter of Authorization for resellers.

blanketLoaInfoobject(BlanketLoaInfo)

You can set up a blanket Letter of Authorization (LoA) that will allow you to import numbers to your account without having to sign an LoA each time you submit a request. To set up a blanket LoA, email your account manager. Once the LoA has been approved, you can use this blanketLoaInfo object in your requests. The blanketLoaInfo object should be sent as an empty object.

scheduledOsrUpdateTimestring(date-time)

The scheduled time for OSR to be updated.

callbackUrlstring

The client's callback URL to be called for text enablement updates.

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/hostingOrders:textEnableNumbers \
  -H 'Content-Type: application/json' \
  -d '{
    "regionCode": "US",
    "numbers": [
      "+17724295286",
      "+17724295287"
    ],
    "servicePlanId": "07d6c2621f364b68856fe4938b7bb78f",
    "campaignId": "C3O8OGA",
    "callbackUrl": "https://www.your-callback-server.com/callback",
    "directLoaInfo": {
      "authorisedPerson": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "email@domain.com"
      },
      "address": {
        "buildingNumber": "2433",
        "street": "Vesta Drive",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60647",
        "country": "US"
      },
      "currentVoiceCarrier": "Verizon"
    },
    "scheduledOsrUpdateTime": "2023-01-13T14:34:40.968Z",
    "migrateToSinchTmo": true
  }'

Responses

A successful response with a hosting order, or an error

Bodyapplication/json
projectIdstring

The project ID to which the hosting order is associated.

Example: "YOUR_project_id"
hostingOrderIdstring

The unique ID of the hosting order.

Example: "YOUR_hosting_order_id"
displayNamestring

The friendly name of the hosting order.

Example: "MyHostingOrder"
regionCodestring

The region code of the hosting order. Number hosting is only available for the US and Canada, so you must enter either "US" or "CA".

Example: "US"
statestring

The state of the hosting order.

Enum ValueDescription
HOSTING_ORDER_STATE_UNSPECIFIED

State is unspecified.

DRAFT

Hosting order is a draft.

SUBMITTED

Hosting order has been submitted.

WAITING_FOR_LOA_SIGNATURE

Hosting order is waiting for the LoA signature.

IN_PROGRESS

Hosting order is in progress.

COMPLETED

Hosting order is completed.

REJECTED

Hosting order is rejected.

typestring

The hosting order type.

Enum ValueDescription
HOSTING_ORDER_TYPE_UNSPECIFIED

The type of hosting order is unspecified.

IMPORT

Hosting order to import numbers.

TYPE_TEXT_ENABLE

Hosting order to text-enable numbers.

createdTimestring(date-time)read-only

Timestamp when the hosting order was created

updatedTimestring(date-time)read-only

Timestamp when the hosting order was last updated

scheduledOsrUpdateTimestring(date-time)read-only

Timestamp when the OSR update will be done

servicePlanIdstring

The service plan to which the hosting order is associated.

Example: "YOUR_service_plan_id"
campaignIdstring

The campaign to which the hosting order is associated.

Example: "YOUR_campaign_id"
migrateToSinchTmobooleanread-only

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

textEnableInfoobject(TextEnableInfo)
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
{
  "projectId": "d1923022-5199-4bb3-a513-c47n7a656bc5",
  "hostingOrderId": "01arz3nhyrtsv4rrffq69g5fav",
  "displayName": "Hosting order with campaignId, nnid and smsAppId",
  "regionCode": "US",
  "state": "SUBMITTED",
  "type": "TYPE_TEXT_ENABLE",
  "createdTime": "2023-01-12T14:34:40.968Z",
  "updatedTime": "2023-01-12T14:34:40.968Z",
  "scheduledOsrUpdateTime": "2023-01-13T14:34:40.968Z",
  "servicePlanId": "16e5c8d2odc842bda9a1b90e1673c174",
  "campaignId": "C3O84GA",
  "migrateToSinchTmo": true,
  "callbackUrl": "https://www.your-callback-server.com/callback",
  "hostingOrderInfo": {
    "businessName": "Sinch AB",
    "authorisedPerson": { … },
    "address": { … },
    "serviceProvider": "Sinch America Inc.",
    "currentVoiceCarrier": "Verizon",
    "nnid": "104029",
    "loaType": "DIRECT"
  }
}

Text enable Toll Free numbers in hosting orders

Request

Text enable Toll Free numbers associated with hosting orders of a specific project.

Security
Basic or OAuth2.0
Path
projectIdstringrequired

Found on your Sinch Customer Dashboard. Settings > Projects.

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

The request to text-enable hosting orders Toll Free numbers in the current project

One of:

Request for text enabling project Toll Free numbers.

directLoaInfoobject(DirectLoaInfo)required

Letter of Authorization for direct Sinch customers.

directLoaInfo.​authorisedPersonobject(AuthorizedPerson)required

The person authorized and responsible for the hosting order.

directLoaInfo.​authorisedPerson.​firstNamestringrequired

The first name of the authorized person.

Example: "John"
directLoaInfo.​authorisedPerson.​lastNamestringrequired

The last name of the authorized person.

Example: "Doe"
directLoaInfo.​authorisedPerson.​emailstringrequired

The email address of the authorized person.

Example: "john.doe@company.com"
directLoaInfo.​addressobject(Address)required

The address of the business.

directLoaInfo.​address.​buildingNumberstringrequired

The building number of the address.

Example: "123"
directLoaInfo.​address.​streetstringrequired

The street name of the address.

Example: "1st"
directLoaInfo.​address.​citystringrequired

The city name of the address.

Example: "New York"
directLoaInfo.​address.​statestringrequired

The state name of the address.

Example: "NY"
directLoaInfo.​address.​postalCodestringrequired

The postal code of the address.

Example: "00001"
directLoaInfo.​address.​countrystringrequired

The country of the address.

Example: "USA"
directLoaInfo.​currentVoiceCarrierstringrequired

The current carrier you are using for voice services for the number you want to host on Sinch.

Example: "TMO"
allOfobject(TextEnableTollFreeNumbersLoaInfoCommon)
curl -i -X POST \
  -u <username>:<password> \
  https://imported.numbers.api.sinch.com/v1/projects/d1923022-5199-4bb3-a513-c47b3a656bc5/hostingOrders:textEnableTollFreeNumbers \
  -H 'Content-Type: application/json' \
  -d '{
    "regionCode": "US",
    "numbers": [
      "+18335870229",
      "+18339460473"
    ],
    "servicePlanId": "07d6c2621f364b68856fe4938b7bb78f",
    "callbackUrl": "https://www.your-callback-server.com/callback",
    "directLoaInfo": {
      "authorisedPerson": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "email@domain.com"
      },
      "address": {
        "buildingNumber": "2433",
        "street": "Vesta Drive",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60647",
        "country": "US"
      },
      "currentVoiceCarrier": "Verizon",
      "scheduledZipwhipProvisioningTime": "2023-01-13T14:34:40.968Z",
      "migrateToSinchTmo": true
    }
  }'

Responses

A successful response with a hosting order, or an error

Bodyapplication/json
projectIdstring

The project ID to which the hosting order is associated.

Example: "YOUR_project_id"
hostingOrderIdstring

The unique ID of the hosting order.

Example: "YOUR_hosting_order_id"
displayNamestring

The friendly name of the hosting order.

Example: "MyHostingOrder"
regionCodestring

The region code of the hosting order. Number hosting is only available for the US and Canada, so you must enter either "US" or "CA".

Example: "US"
statestring

The state of the hosting order.

Enum ValueDescription
HOSTING_ORDER_STATE_UNSPECIFIED

State is unspecified.

DRAFT

Hosting order is a draft.

SUBMITTED

Hosting order has been submitted.

WAITING_FOR_LOA_SIGNATURE

Hosting order is waiting for the LoA signature.

IN_PROGRESS

Hosting order is in progress.

COMPLETED

Hosting order is completed.

REJECTED

Hosting order is rejected.

typestring

The hosting order type.

Enum ValueDescription
HOSTING_ORDER_TYPE_UNSPECIFIED

The type of hosting order is unspecified.

IMPORT

Hosting order to import numbers.

TYPE_TEXT_ENABLE

Hosting order to text-enable numbers.

createdTimestring(date-time)read-only

Timestamp when the hosting order was created

updatedTimestring(date-time)read-only

Timestamp when the hosting order was last updated

scheduledOsrUpdateTimestring(date-time)read-only

Timestamp when the OSR update will be done

servicePlanIdstring

The service plan to which the hosting order is associated.

Example: "YOUR_service_plan_id"
campaignIdstring

The campaign to which the hosting order is associated.

Example: "YOUR_campaign_id"
migrateToSinchTmobooleanread-only

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

textEnableInfoobject(TextEnableInfo)
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
{
  "projectId": "d1923022-5199-4bb3-a513-c47n7a656bc5",
  "hostingOrderId": "01arz3nhyrtsv4rrffq69g5fav",
  "displayName": "Hosting order with campaignId, nnid and smsAppId",
  "regionCode": "US",
  "state": "SUBMITTED",
  "type": "TYPE_TEXT_ENABLE",
  "createdTime": "2023-01-12T14:34:40.968Z",
  "updatedTime": "2023-01-12T14:34:40.968Z",
  "scheduledOsrUpdateTime": "2023-01-13T14:34:40.968Z",
  "servicePlanId": "16e5c8d2odc842bda9a1b90e1673c174",
  "campaignId": "C3O84GA",
  "migrateToSinchTmo": true,
  "callbackUrl": "https://www.your-callback-server.com/callback",
  "hostingOrderInfo": {
    "businessName": "Sinch AB",
    "authorisedPerson": { … },
    "address": { … },
    "serviceProvider": "Sinch America Inc.",
    "currentVoiceCarrier": "Verizon",
    "nnid": "104029",
    "loaType": "DIRECT"
  }
}

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

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