# Imported Numbers and Hosting Orders

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

Version: 1.0
License: MIT

## Servers

Global API
```
https://imported.numbers.api.sinch.com
```

## Security

### Basic

Your key ID and Key secret serve as the username and password, respectively. Both can be found in the <a href='dashboard.sinch.com/settings/access-keys' target='_blank'>Sinch Customer Dashboard</a>.For more information about basic authentication in the Numbers API, click [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/basic).

Type: http
Scheme: basic

### OAuth2.0

The username and password are your Key ID and Key Secret from the <a href="https://dashboard.sinch.com/settings/access-keys" target="_blank">Access keys section</a> in the Sinch Customer Dashboard. Exchange these for a bearer token (access token). Learn how [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth).

Type: oauth2

## Download OpenAPI description

[Imported Numbers and Hosting Orders](https://developers.sinch.com/_spec/docs/numbers/api-reference/imported-hosting.yaml)

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

### List hosting orders

 - [GET /v1/projects/{projectId}/hostingOrders](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/hostingorderservice_listhostingorders.md): Lists the hosting orders for the project.

### Get hosting order

 - [GET /v1/projects/{projectId}/hostingOrders/{hostingOrderId}](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/hostingorderservice_gethostingorder.md): Returns the hosting order specified by the hosting order ID.

### Retrieve a hosting order report

 - [GET /v1/projects/{projectId}/hostingOrders/{hostingOrderId}/report](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/gethostingorderreport.md): Returns the report object for a specific hosting order

### List hosting order numbers

 - [GET /v1/projects/{projectId}/hostingOrders/{hostingOrderId}/numbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/hostingorderservice_listhostingordernumbers.md): Lists the numbers belonging to the specified hosting order.

### Get hosting order number

 - [GET /v1/projects/{projectId}/hostingOrders/{hostingOrderId}/numbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/hostingorderservice_gethostingordernumber.md): Returns the specified phone number belonging to the specified hosting order.

### Import numbers using hosting orders

 - [POST /v1/projects/{projectId}/hostingOrders:importNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/hostingorderservice_importnumbers.md): 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.

### Text enable numbers in hosting orders

 - [POST /v1/projects/{projectId}/hostingOrders:textEnableNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/textenablenumbers.md): Text enable numbers associated with hosting orders of a specific project.

### Text enable Toll Free numbers in hosting orders

 - [POST /v1/projects/{projectId}/hostingOrders:textEnableTollFreeNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/hosting-orders/textenabletollfreenumbers.md): Text enable Toll Free numbers associated with hosting orders of a specific project.

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

 - [GET /v1/projects/{projectId}/importedNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers/importnumberservice_listimportednumbers.md): Lists all imported numbers for the project.

### Import number

 - [POST /v1/projects/{projectId}/importedNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers/importnumberservice_importnumber.md): 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)?

### Get imported number

 - [GET /v1/projects/{projectId}/importedNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers/importnumberservice_getimportednumber.md): Returns the imported number you specify in the path.

### Delete imported number

 - [DELETE /v1/projects/{projectId}/importedNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers/importnumberservice_deleteimportednumber.md): Delete an imported number from the project.

### Update imported number

 - [PATCH /v1/projects/{projectId}/importedNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers/importnumberservice_updateimportednumber.md): Update an imported phone number. You can perform the following updates:

* Update the name that displays for a customer by modifying the  parameter.
* Unlink the number from an SMS service or campaign by updating the  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.

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

### List qualified numbers

 - [GET /v1/projects/{projectId}/qualifiedNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberservice_listqualifiednumbers.md): Returns a list of qualified numbers for the project.

### Get qualified number

 - [GET /v1/projects/{projectId}/qualifiedNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberservice_getqualifiednumber.md): Return a qualified number as specified by the phone number in the path.

### Delete qualified number

 - [DELETE /v1/projects/{projectId}/qualifiedNumbers/{phoneNumber}](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberservice_deletequalifiednumber.md): Deletes a qualified number as specified by the phone number in the path.

### Create qualified number batch

 - [POST /v1/projects/{projectId}/qualifiedNumbers:addNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberservice_batchcreatequalifiednumbers.md): Create a request to qualify a batch of numbers. After you have submitted the request, you must send an email to orders@sinch.com attaching all of the invoices related to the phone numbers in the request. In most cases, it will take the Sinch team 1-3 days to review your documentation and qualify your numbers.

### Text enable numbers

 - [POST /v1/projects/{projectId}/qualifiedNumbers:textEnableNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberservice_textenablenumbers.md): Enables text capability for the specified qualified numbers. You can enable up to 500 numbers at once. To enable a number for SMS, you must include a Campaign ID and billing information for a Letter of Authorization to be generated. The information required can differ depending on if you are a direct customer of Sinch or a reseller. The Letter of Authorization will be sent to the email you provide in the request to be e-signed.

### Text enable Toll Free qualified numbers

 - [POST /v1/projects/{projectId}/qualifiedNumbers:textEnableTollFreeNumbers](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberstextenabletollfreenumbers.md): Text enable Toll Free qualified numbers of a specific project by creating a hosting order.

### Verify voice challenge

 - [POST /v1/projects/{projectId}/qualifiedNumbers/{phoneNumber}:verifyVoiceChallenge](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberservice_verifyvoicechallenge.md): Uses the code you received from the Send voice challenge operation to verify that you own the phone number.

### Send voice challenge

 - [POST /v1/projects/{projectId}/qualifiedNumbers/{phoneNumber}:sendVoiceChallenge](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/qualified-numbers/qualifiednumberservice_sendvoicechallenge.md): Sends a voice challenge to the phone number specified in the path to verify that you own the number. The voice call contains a code that you must use to verify the number.

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

### Secure Webhook Endpoints with HMAC

Implementing HMAC (Hash-based Message Authentication Code) on your webhook endpoints will ensure the integrity of data, preventing tampering during transmission.
An HMAC used in webhooks is a common approach in the industry and essentially it is just special code that can be used to check if a message hasn't been tampered with during the transmission.

We recommend to configure an HMAC secret for your project using the [callback configuration](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers-and-hosting-orders-callbacks/updatecallbackconfiguration). Then, when sending the number events, the HTTP POST requests will include the header `X-Sinch-Signature` with the computed HMAC.

**NOTE:** The HMAC secret is configured per project; if you are using the Numbers API with multiple projects, make sure you configure the HMAC secret in each project, and fetch it for either imported or purchased numbers from the dedicated endpoints.

### HMAC verification

We recommend to verify the HMAC code received with every event in your event handler. When receiving a new event on your endpoint URL, compute the HMAC of the payload using the secret (configured [here](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers-and-hosting-orders-callbacks/updatecallbackconfiguration)) and compare it with one received in the `X-Sinch-Signature` header.

**NOTE:** Compute the HMAC on the plain text value before parsing the JSON payload.

### Get callbacks configuration

 - [GET /v1/projects/{projectId}/callbackConfiguration](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers-and-hosting-orders-callbacks/getcallbackconfiguration.md): Returns the callbacks configuration for the specified project

### Update callback configuration

 - [PATCH /v1/projects/{projectId}/callbackConfiguration](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers-and-hosting-orders-callbacks/updatecallbackconfiguration.md): Updates the callbacks configuration for the specified project

### Event notification

 - [POST EventsCallback](https://developers.sinch.com/docs/numbers/api-reference/imported-hosting/imported-numbers-and-hosting-orders-callbacks/importednumberservice_eventscallback.md): A notification of an event sent to your configured callback URL.