# Porting API Automated processing of port-in phone number operations Version: 1.0 License: MIT ## Servers v1.0 of the porting API ``` https://porting.api.sinch.com/v1/projects/{projectId} ``` Variables: - `projectId`: The project with which you are working. Default: "YOUR_project_id" ## Security ### basicAuth Your key ID and Key secret serve as the username and password, respectively. Both can be found in the [Sinch Build Dashboard](https://dashboard.sinch.com/settings/access-keys). 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 ### bearerAuth The username and password are your Key ID and Key Secret from the [Sinch Build Dashboard](https://dashboard.sinch.com/settings/access-keys). 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 [Porting API](https://developers.sinch.com/_spec/docs/numbers/api-reference/porting.yaml) ## Port-in numbers You can create orders, check portability, and more. When you port in phone numbers to Sinch you need to make sure the numbers are portable, you can use the portability check to make sure the numbers are portable before creating an order. If a number is not portable the whole order will fail. When porting a number to Sinch you can either use the dashboard or the API, the API is recommended for larger orders and for automation. **Note:** For port orders of over 500 numbers, please contact the [support team](https://tickets.sinch.com/plugins/servlet/desk/portal/31/create/1572). The recommended way to port numbers to Sinch is to schedule the port, this means that you create an order and specify a desired port date and time, If you have more advanced needs like on-demand activation, you can read more about that in the [advanced porting section](https://developers.sinch.com/docs/numbers/api-reference/porting/advanced-porting/). ### Porting orders In general you work with porting orders, a porting order is the resource that keeps the number(s) status and progress in one place. Before creating port order you should check the portability of the numbers you want to port in, if a number is not portable the order will fail. ```json POST /portabilityChecks { "phoneNumbers": ["+12345678901"] } ``` If the number is portable you can create an order like this: ```json POST v1/projects/{projectId}/orders/portIns { "desiredPortSchedule": { "desiredPortDate": "2024-09-25", }, "phoneNumbers": [ { "phoneNumber": "+12345678901", "voiceConfiguration": { "type": "EST", "trunkId": "123456" }, "portOutInfo": { "existingPortOutPin": "1234" }, "endUser": { "name": "John Doe", "streetName": "Main St", "streetNum": "123", "city": "Anytown", "state": "NY", "zipCode": "12345" }, } ] } ``` #### Lifetime of a port order If everything is correct, the order run thru is life cycle and keep you updated on changes but hopefully nothing will change and the number will be ported in on the desired port date. If more information is needed from you, it will be communicated to you via the order notes and error statuses on the individual numbers. And you reply with a note or update your order with required information. It's not uncommon for a port order to be a few days or weeks in the making, so don't worry if you don't receive an update right away. ### Port-In phone numbers When you port in phone numbers to Sinch you need to make sure the numbers are portable, you can use the portability check to make sure the numbers are portable before creating an order. ### Porting availability - [POST /portabilityChecks](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/checkportingavailability.md): Use this before creating a order to make sure all numbers are available for port in to Sinch. Please note that if you try to port a number that is not portable the order will fail. ### Create port-in order - [POST /orders/portIns](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/orderportin.md): Create an order to port phone numbers from another carrier into Sinch. Refer to the Port-In Status section for more information on port-in order updates. Please note that order will fail if you try to port numbers that are not portable, so you should always use the portability check before creating an order. Note: For port orders of over 500 numbers, please contact the support team. In order to send SMS and MMS messages in the US using 10DLC phone numbers, all messages must be sent via an approved campaign. Your campaigns are managed under US 10DLC Campaigns in the SMS section. A number can be associated to an approved campaign after the port completes. ### List port-in orders - [GET /orders/portIns](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/getportinorders.md): Retrieve a list of port-in based on the search parameters, you can also specify view here to get less detail ### Get order Detail - [GET /orders/portIns/{orderId}](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/getorderdetails.md): Get details about an existing order along with order notes and process notes (for Port-In orders). For realtime updates on the order status, please refer to the Webhooks section. wich is the recommended way to get updates on the order status. ### Cancel Pending Order - [DELETE /orders/portIns/{orderId}](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/deleteorder.md): This operation allows you to cancel an order in Pending status. ### Update port-in order - [PUT /orders/portIns/{orderId}](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/updateportinorder.md): This operation allows you to update information on a Pending order. Please note that you need to send the full object, its not a patch ### Add Order Note - [POST /orders/portIns/{orderId}/notes](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/addordernote.md): This operation allows you to add a note to an existing order. ### Add Order Document - [POST /orders/portIns/{orderId}/documents](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/addorderdocuments.md): This operation allows you to add a document to an existing order. ### Get document content - [GET /orders/{orderId}/documents/{documentId}](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-numbers/getorderdocumentcontent.md): This operation allows you to retrieve specific document contents attached to an existing order. ## Webhooks ## Webhooks for porting Sinch uses webhooks to notify you of events that happen in the porting system. You can configure webhooks for porting events in the porting defaults API or via the dashboard. Anytime a port is then made via the dashboard or we at Sinch trigger an update we will call your webhook url with the event type and a payload depending on event type. ### Order Updated - [POST OrderUpdated](https://developers.sinch.com/docs/numbers/api-reference/porting/webhooks/order.md): This is a webhook that will be called when an order is updated, it will contain the order and the status of the order. ### Number activated - [POST NumbersActivated](https://developers.sinch.com/docs/numbers/api-reference/porting/webhooks/numbersactivated.md): This notification occurs if at least one number on the port order was activated. ### Number confirmed - [POST NumbersConfirmed](https://developers.sinch.com/docs/numbers/api-reference/porting/webhooks/numbersconfirmed.md): This notification occurs when at least one number on the port order was confirmed. This notification also occurs when the number is ready to be activated and was set to true or if it will be activated at the specified confirmation date. ### Number Rejected - [POST NumbersRejected](https://developers.sinch.com/docs/numbers/api-reference/porting/webhooks/numbersrejected.md): This notification occurs if at least one number on the port order was rejected. Look at rejected reasons for more details on what went wrong. ### Note added to order - [POST NewOrderNote](https://developers.sinch.com/docs/numbers/api-reference/porting/webhooks/newordernote.md): This notification occurs if a note was added to the order either by Sinch or by you. ## Port-in settings Porting default settings ### Create Configuration - [POST /configuration](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-settings/createconfiguration.md): Create default Configuration for a given project ### Get Configuration - [GET /configuration](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-settings/getconfiguration.md): Retrieve Notification Configuration for a given project ### Update configuration - [PUT /configuration](https://developers.sinch.com/docs/numbers/api-reference/porting/port-in-settings/updateconfiguration.md): Update default configurations for a given project ## Advanced porting This section is for advanced porting operations, like on demand activating numbers, getting available numbers for activation, and more. If you are looking for basic porting operations like creating an order, checking portability, and more, please refer to the Port-in numbers section. ### Scheduled ports The recommended way to port numbers to Sinch is to schedule the port, this means that you create an order and specify a desired port date and time, this is the date you want the numbers to be ported in to Sinch automatically and we will sync with the loosing carrier to make sure the port is done on that date with minimal downtime for you and your customers. ### On demand ports If you need to control your self when a number is activated you can use on demand ports, that means as soon as the number is confirmed you can activate it when you want. And we take care of the rest. When using on demand ports you need to make sure the number is confirmed and released for activation. you can also choose to activate numbers on activation groups. ### Activation groups When you create a port in order we assign an activating group on the numbers, the grouping is by carrier so if you have a large port-in order from multiple different carriers you can group and look at the numbers by group to see status. Updates to port order usually comes on group basis and are confirmed ro rejected on carrier level. You can also use this as a way to activate groups for on-demand activation. However we recommend you porting in numbers by carrier to make sure you get the best experience. ### On demand activation When you set up an order with onDemandActivation set to true, you can activate the numbers when you want. This is useful if you want to control when the numbers are activated. You can activate a whole order by calling `/orders/portins/{orderId}/activate` or you can activate a specific group of numbers by calling `/orders/portins/{orderId}/activate` with the phoneNumberGroup you find on the number. Please note that it is not possible to activate single numbers by order or activation group. ### List port-in activation groups - [GET /orders/portIns/{orderId}/availableActivations](https://developers.sinch.com/docs/numbers/api-reference/porting/advanced-porting/getportinavailableactivation.md): Retrieve Port-In Order Available Activation Groups This operation allows you to get a list of phone number groups currently available for activation on a port-in order. FOC (portDate) must be today or earlier, and the numbers must be in routing on the Sinch network. ### On demand activation - [POST /orders/portIns/{orderId}/activate](https://developers.sinch.com/docs/numbers/api-reference/porting/advanced-porting/activateportin.md): Activate numbers that are ready to be ported. Confirmation date (FOC) must be today or earlier, and the numbers must be in routing on the Sinch network (occurs at midnight on the date of the port, after concurrence, or following the 18-hour wireline port timer expiration on expedited ports). In order to send SMS and MMS messages in the US using 10DLC phone numbers, all messages must be sent via an approved campaign. Your campaigns are managed under US 10DLC Campaigns in the SMS section. A number can be associated to an approved campaign after the port completes.