Automated processing of port-in phone number operations
Porting API (1.0)
Download OpenAPI description
Overview
License
Languages
Servers
v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/{projectId}/
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.
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.
Operations
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.
POST /portabilityChecks
{
"phoneNumbers": ["+12345678901"]
}If the number is portable you can create an order like this:
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"
},
}
]
}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.
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.
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/portabilityChecks
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://porting.api.sinch.com/v1/projects/YOUR_project_id/portabilityChecks \
-H 'Content-Type: application/json' \
-d '{
"phoneNumbers": [
"+12311234567"
]
}'Response
application/json
{ "phoneNumbers": [ { … } ] }
Request
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.
Note: 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.
Security
basicAuth or bearerAuth
Order Port-In phone numbers
The date and time you want the numbers to be ported in. If you set a defaultPortTime and defaultPortTimeZone in defaults those settings will be used if not set per order. If you haven't set defaults and do not set the time and time zone on the order the system default will be used.
System Default Time: 09:00:00 US/Eastern
The date you want the numbers to be ported in, in ISO format.
Example: "2025-01-31"
The time you want the numbers to be ported in.
Example: "09:00:00"
The numbers for the order in e164 format
The phone number in E.164 format.
Example: "+12345678901"
If specified, this will override the endUser for the order.
The name of the end user can be a person's name or company name. Please note if you are not using this yourself it should be the name/company of the actual user.
Example: "Joe Doe"
The end user's state, using the two letter abbreviation.
Example: "CA"
The prefix direction in the end user's address, if any.
Default ""
Example: "N"
The end user's street type, for example Road or Court.
Default ""
Example: "Court"
The suffix direction in the end user's address, if any.
Default ""
Example: "SW"
Any additional location information, such as suite or apartment.
Example: "Suite"
Any additional location information, such as suite number or apartment number.
Example: "2134"
Field for additional location information, such as suite number or apartment number.
Default ""
Example: ""
Field for additional location information, such as suite number or apartment number.
Default ""
Example: ""
Field for additional location information, such as suite number or apartment number.
Default ""
Example: ""
Field for additional location information, such as suite number or apartment number.
Default ""
Example: ""
The port out information at the previous carrier for the number. Usually only a port-out PIN is required.
The existing port-out PIN from the previous carrier.
The account number associated with the number from the previous carrier.
Date of authorizing the port-in (must be today or earlier and cannot be in the future). Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
One of:
If specified, this will override the voice configuration for the order.
If specified, this will override the sms configuration for the order.
Your reference you specified when creating the order
Default ""
Example: "123456"
If you use onDemand activation you will need to make sure the numbers are both confirmed and released for activation, if you don't use onDemand the numbers will be activated on the desiredPortDate is the recommended way. If true the numbers will be activated as when you call :activate, if false they will be activated on the desiredPortDate
Default false
Date when the LOA was uploaded. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns \
-H 'Content-Type: application/json' \
-d '{
"desiredPortSchedule": {
"desiredPortDate": "2025-01-31",
"desiredPortTime": "10:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"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"
}
}
]
}'Successful operation
The date and time you want the numbers to be ported in. If you set a defaultPortTime and defaultPortTimeZone in defaults those settings will be used if not set per order. If you haven't set defaults and do not set the time and time zone on the order the system default will be used.
System Default Time: 09:00:00 US/Eastern
The date you want the numbers to be ported in, in ISO format.
Example: "2025-01-31"
The time you want the numbers to be ported in.
Example: "09:00:00"
The current status of the port order.
| Enum Value | Description |
|---|---|
| ORDER_BUILDING | The order is being created |
| PENDING | The order is pending, and can be updated |
| CONFIRMED | The order is confirmed, and can not be updated but if onDemand is true it can be activated |
| COMPLETED | The order is completed, the port has completed and the numbers are active |
| PENDING_CANCELATION | The order is in the process of being cancelled. During this time you cannot submit the same numbers on a new order |
| CANCELED | The order is cancelled, either by the customer or by the system |
Your reference you specified when creating the order
Default ""
Example: "123456"
If you use onDemand activation you will need to make sure the numbers are both confirmed and released for activation, if you don't use onDemand the numbers will be activated on the desiredPortDate is the recommended way. If true the numbers will be activated as when you call :activate, if false they will be activated on the desiredPortDate
Default false
Date when the LOA was uploaded. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
Notes if any on the order, you will get notes if there is any problems with the order and you send notes as reply to those problems
Documents if any on the order, you will get documents if there is any problems with the order and you send documents as reply to those problems
When the order was created. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
Response
application/json
{ "id": 890192331, "status": "PENDING", "customerOrderReference": "123456", "onDemandActivation": false, "desiredPortSchedule": { "desiredPortDate": "2025-01-31", "desiredPortTime": "09:00:00", "desiredPortTimeZone": "US/Eastern" }, "loaUploadedBy": "john doe", "loaAttachmentDate": "2024-09-24T12:00:00Z", "phoneNumbers": [ { … } ], "notes": [ { … } ], "documents": [ { … } ], "createdDate": "2024-09-24T12:00:00Z", "resellerName": "" }
Query
Search by the status of the order.
| Enum Value | Description |
|---|---|
| ORDER_BUILDING | The order is being created |
| PENDING | The order is pending, and can be updated |
| CONFIRMED | The order is confirmed, and can not be updated but if onDemand is true it can be activated |
| COMPLETED | The order is completed, the port has completed and the numbers are active |
| PENDING_CANCELATION | The order is in the process of being cancelled. During this time you cannot submit the same numbers on a new order |
| CANCELED | The order is cancelled, either by the customer or by the system |
Search by the created date. This query sets the start date of the search period. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: createdDateStart=2024-09-24T12:00:00Z
Search by the created date. This query sets the end date of the search period. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: createdDateEnd=2024-09-24T12:00:00Z
Search by the firm order confirmation. This query sets the start date of the search period. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: focStartDate=2024-09-24T12:00:00Z
Search by the firm order confirmation. This query sets the end date of the search period. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: focEndDate=2024-09-24T12:00:00Z
The maximum number of items to return per request. The default is 100 and the maximum is 1000. If you need to export larger amounts and pagination is not suitable for you can use the Export function in the dashboard.
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns?orderId=0&orderStatus=PENDING&customerOrderReference=string&createdDateStart=2024-09-24T12%3A00%3A00Z&createdDateEnd=2024-09-24T12%3A00%3A00Z&phoneNumber=string&focStartDate=2024-09-24T12%3A00%3A00Z&focEndDate=2024-09-24T12%3A00%3A00Z&pageSize=1&page=string'Response
application/json
{ "orders": [ { … } ], "page": 0, "totalPages": 0, "pageSize": 0, "totalItems": 0 }
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/897867Successful operation
The date and time you want the numbers to be ported in. If you set a defaultPortTime and defaultPortTimeZone in defaults those settings will be used if not set per order. If you haven't set defaults and do not set the time and time zone on the order the system default will be used.
System Default Time: 09:00:00 US/Eastern
The date you want the numbers to be ported in, in ISO format.
Example: "2025-01-31"
The time you want the numbers to be ported in.
Example: "09:00:00"
The current status of the port order.
| Enum Value | Description |
|---|---|
| ORDER_BUILDING | The order is being created |
| PENDING | The order is pending, and can be updated |
| CONFIRMED | The order is confirmed, and can not be updated but if onDemand is true it can be activated |
| COMPLETED | The order is completed, the port has completed and the numbers are active |
| PENDING_CANCELATION | The order is in the process of being cancelled. During this time you cannot submit the same numbers on a new order |
| CANCELED | The order is cancelled, either by the customer or by the system |
Your reference you specified when creating the order
Default ""
Example: "123456"
If you use onDemand activation you will need to make sure the numbers are both confirmed and released for activation, if you don't use onDemand the numbers will be activated on the desiredPortDate is the recommended way. If true the numbers will be activated as when you call :activate, if false they will be activated on the desiredPortDate
Default false
Date when the LOA was uploaded. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
Notes if any on the order, you will get notes if there is any problems with the order and you send notes as reply to those problems
Documents if any on the order, you will get documents if there is any problems with the order and you send documents as reply to those problems
When the order was created. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
Response
application/json
{ "id": 890192331, "status": "PENDING", "customerOrderReference": "123456", "onDemandActivation": false, "desiredPortSchedule": { "desiredPortDate": "2025-01-31", "desiredPortTime": "09:00:00", "desiredPortTimeZone": "US/Eastern" }, "loaUploadedBy": "john doe", "loaAttachmentDate": "2024-09-24T12:00:00Z", "phoneNumbers": [ { … } ], "notes": [ { … } ], "documents": [ { … } ], "createdDate": "2024-09-24T12:00:00Z", "resellerName": "" }
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/897867Bodyapplication/jsonrequired
Update Pending Order
The date and time you want the numbers to be ported in. If you set a defaultPortTime and defaultPortTimeZone in defaults those settings will be used if not set per order. If you haven't set defaults and do not set the time and time zone on the order the system default will be used.
System Default Time: 09:00:00 US/Eastern
The date you want the numbers to be ported in, in ISO format.
Example: "2025-01-31"
The time you want the numbers to be ported in.
Example: "09:00:00"
Your reference you specified when creating the order
Default ""
Example: "123456"
If you use onDemand activation you will need to make sure the numbers are both confirmed and released for activation, if you don't use onDemand the numbers will be activated on the desiredPortDate is the recommended way. If true the numbers will be activated as when you call :activate, if false they will be activated on the desiredPortDate
Default false
Date when the LOA was uploaded. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
-u <username>:<password> \
'https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}' \
-H 'Content-Type: application/json' \
-d '{
"customerOrderReference": "123456",
"onDemandActivation": false,
"desiredPortSchedule": {
"desiredPortDate": "2025-01-31",
"desiredPortTime": "09:00:00",
"desiredPortTimeZone": "US/Eastern"
},
"loaUploadedBy": "john doe",
"loaAttachmentDate": "2024-09-24T12:00:00Z",
"phoneNumbers": [
{
"phoneNumber": "+12345678901",
"voiceConfiguration": {
"type": "RTC",
"appId": "6afd2da3-1692-4443-834c-8a2f386ec284"
},
"smsConfiguration": {
"smsAppId": "string"
},
"endUser": {
"name": "Joe Doe",
"streetNum": "123",
"streetName": "Main",
"streetPreDir": "N",
"streetType": "Court",
"streetPostDir": "SW",
"locationType1": "Suite",
"locationValue1": "2134",
"locationType2": "",
"locationValue2": "",
"locationType3": "",
"locationValue3": "",
"city": "Anytown",
"state": "CA",
"zipCode": "12345",
"typeOfService": "B"
},
"portOutInfo": {
"existingPortOutPin": "string",
"accountNum": "string",
"accountPhoneNumber": "string",
"authorizingName": "string",
"authorizingDate": "2024-09-24T12:00:00Z"
},
"features": {
"e911": {
"name": "string",
"streetNum": "12345",
"streetInfo": "Main St",
"location": "Apt 5",
"city": "Springfield",
"state": "IL",
"postalCode": "62701",
"postalCodePlusFour": "1234"
}
},
"newPortOutPin": "string"
}
],
"resellerName": ""
}'Successful operation
The date and time you want the numbers to be ported in. If you set a defaultPortTime and defaultPortTimeZone in defaults those settings will be used if not set per order. If you haven't set defaults and do not set the time and time zone on the order the system default will be used.
System Default Time: 09:00:00 US/Eastern
The date you want the numbers to be ported in, in ISO format.
Example: "2025-01-31"
The time you want the numbers to be ported in.
Example: "09:00:00"
The current status of the port order.
| Enum Value | Description |
|---|---|
| ORDER_BUILDING | The order is being created |
| PENDING | The order is pending, and can be updated |
| CONFIRMED | The order is confirmed, and can not be updated but if onDemand is true it can be activated |
| COMPLETED | The order is completed, the port has completed and the numbers are active |
| PENDING_CANCELATION | The order is in the process of being cancelled. During this time you cannot submit the same numbers on a new order |
| CANCELED | The order is cancelled, either by the customer or by the system |
Your reference you specified when creating the order
Default ""
Example: "123456"
If you use onDemand activation you will need to make sure the numbers are both confirmed and released for activation, if you don't use onDemand the numbers will be activated on the desiredPortDate is the recommended way. If true the numbers will be activated as when you call :activate, if false they will be activated on the desiredPortDate
Default false
Date when the LOA was uploaded. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
Notes if any on the order, you will get notes if there is any problems with the order and you send notes as reply to those problems
Documents if any on the order, you will get documents if there is any problems with the order and you send documents as reply to those problems
When the order was created. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Example: "2024-09-24T12:00:00Z"
Response
application/json
{ "id": 890192331, "status": "PENDING", "customerOrderReference": "123456", "onDemandActivation": false, "desiredPortSchedule": { "desiredPortDate": "2025-01-31", "desiredPortTime": "09:00:00", "desiredPortTimeZone": "US/Eastern" }, "loaUploadedBy": "john doe", "loaAttachmentDate": "2024-09-24T12:00:00Z", "phoneNumbers": [ { … } ], "notes": [ { … } ], "documents": [ { … } ], "createdDate": "2024-09-24T12:00:00Z", "resellerName": "" }
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}/notes
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}/notes' \
-H 'Content-Type: application/json' \
-d '{
"note": "string"
}'Response
application/json
{ "id": 0, "note": "string" }
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}/documents
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/portIns/{orderId}/documents' \
-H 'Content-Type: application/json' \
-d '{
"documentName": "string",
"description": "string",
"fileContent": "string"
}'Response
application/json
{ "id": 0, "documentName": "string", "description": "string" }
- v1.0 of the porting API
https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/{orderId}/documents/{documentId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://porting.api.sinch.com/v1/projects/YOUR_project_id/orders/{orderId}/documents/{documentId}'Response
application/json
{ "documentId": 0, "id": 0, "documentName": "string", "description": "string", "fileContent": "string", "contentType": "string" }
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.
Operations