Download OpenAPI specification:Download

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.

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.

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"
          },
        }
      ]
    }
    ```

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

a phone port item

phoneNumber
required
string <e164>
required
object (EndUser)

if specified will override the endUser for the order

name
required
string

The name of the end user can be person or company name, please not if you are not using this your self it should be the name/company of the actual user.

streetNum
required
string

The street number

streetName
required
string
city
required
string

The city of the end user

state
required
string

State two letter abbreviation

zipCode
required
string
Default: ""
streetPreDir
string
Default: ""
streetType
string
Default: ""
streetPostDir
string
Default: ""
locationType1
string

your own location information surch as suite etc use this to describe it

locationValue1
string

your own location information surch as suite etc, put value here

locationType2
string
Default: ""
locationValue2
string
Default: ""
locationType3
string
Default: ""
locationValue3
string
Default: ""
typeOfService
string
Default: "B"

Available values are B, Business, R, and Residence

Enum Value Description
B

Business

R

Residence

required
object (PortOutItem)

if specified will override the endUser for the order

existingPortOutPin
string
accountNum
string
accountPhoneNumber
string
authorizingName
string

Name of the person authorizing the port in

authorizingDate
string

Date of authorizing the port in (must be today or earlier and cannot be in the future)

status
string
Default: "PENDING"
Enum Value Description
PENDING

The number is pending, and can be updated

CONFIRMED

The number is confirmed, and can not be updated but if onDemand is true it can be activated

REJECTED

The number is rejected, look at the rejectReason for more details it can be either its not portable or wrong port out info

ACTIVATED

The number is activated

CANCELED

The number is cancelled, either by the customer or by the system

EXCLUDED

The number is excluded from the order, look at the exclusionReason for more details

exclusionReason
string
Default: ""

If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.

exclusionTime
string <date-time>

If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.

countryCode
string

The country code of the number ISD code US, SE etc. At the moment only north american numbers are supported

activateTime
string

the time the number was activated UTC timezone

activateUser
string

The user that activated the number

RTC (object) or EST (object) or FAX (object) (VoiceConfiguration)
One of:

if specified will override the voice configuration for the order

type
string
Default: "RTC"
Value: "RTC"
appId
string

The app id from the dashboard where you want to use the number

object (SmsConfiguration)

if specified will override the sms configuration for the order

smsAppId
string
object (Feature)
object
name
string
streetNum
string
streetInfo
string
location
string
city
string
state
string
postalCode
string
postalCodePlusFour
string
enhStreetNum
string

Once E911 Address validation is completed, "enh" (enhanced) attributes are populated

enhStreetInfo
string

Once E911 Address validation is completed, "enh" (enhanced) attributes are populated

enhLocation
string

Once E911 Address validation is completed, "enh" (enhanced) attributes are populated

enhCity
string

Once E911 Address validation is completed, "enh" (enhanced) attributes are populated

enhState
string

Once E911 Address validation is completed, "enh" (enhanced) attributes are populated

enhPostalCode
string

Once E911 Address validation is completed, "enh" (enhanced) attributes are populated

enhPostalCodePlusFour
string

Once E911 Address validation is completed, "enh" (enhanced) attributes are populated

newPortOutPin
string
rejectReason
string

The reason the number was rejected

Array of objects
Array
featureName
string
exclusionReason
string
phoneNumberGroup
string
focDate
string <date-time>

Once the phone number has a firm order confirmation date, it will be returned as part of the phone number details.

{
  • "phoneNumber": "+12345678901",
  • "status": "PENDING",
  • "exclusionReason": "",
  • "exclusionTime": "2019-08-24T14:15:22Z",
  • "countryCode": "US",
  • "activateTime": "14:00",
  • "activateUser": "string",
  • "voiceConfiguration": {
    • "type": "RTC",
    • "appId": "6afd2da3-1692-4443-834c-8a2f386ec284"
    },
  • "smsConfiguration": {
    • "smsAppId": "string"
    },
  • "endUser": {
    • "name": "Joe Doe",
    • "streetNum": 123,
    • "streetName": "Main St",
    • "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": "string"
    },
  • "features": {
    • "e911": {
      }
    },
  • "newPortOutPin": "string",
  • "rejectReason": "string",
  • "excludedFeatures": [
    • {
      }
    ],
  • "phoneNumberGroup": "GW Verizon Grp1",
  • "focDate": "2019-08-24T14:15:22Z"
}

Porting availability

Use this before creating a order to make sure all numbers are available for port in to Sinch. Please not that if you try to port a number that is not portable the order will fail.

SecuritybasicAuth or bearerAuth
Request
Request Body schema: application/json
required
phoneNumbers
Array of strings
Responses
200

Successful operation

Response Schema: application/json
Array of objects
Array
phoneNumber
string
portable
boolean
carrier
string
reason
string

Optional, included only if not portable

post/portabilityChecks
Request samples
application/json
{ }
Response samples
application/json
{
  • "phoneNumbers": [
    • {
      }
    ]
}

Create port-in order

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.

SecuritybasicAuth or bearerAuth
Request
Request Body schema: application/json
required

Order Port-In phone numbers

required
object (DesiredPortDateTime)

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

desiredPortDate
required
string

The date you want the numbers to be ported in, in ISO format.

desiredPortTime
string

The time you want the numbers to be ported in.

desiredPortTimeZone
string

The time zone you want to use for the desired port time.

Enum Value Description
US/Eastern

US Eastern Timezone

US/Central

US Central Timezone

US/Mountain

US Mountain Timezone

US/Pacific

US Pacific Timezone

required
Array of objects (Phone numbers)

The numbers for the order in e164 format

Array
phoneNumber
required
string <e164>
required
object (EndUser)

if specified will override the endUser for the order

required
object (PortOutItem)

if specified will override the endUser for the order

RTC (object) or EST (object) or FAX (object) (VoiceConfiguration)
object (SmsConfiguration)

if specified will override the sms configuration for the order

object (Feature)
newPortOutPin
string
customerOrderReference
string
Default: ""

Your reference you specified when creating the order

onDemandActivation
boolean
Default: false

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

resellerName
string
Default: ""

This is requirement for canadian numbers only, we need to figure out what we expect here and where the customer can find this info

Responses
201

Successful operation

Response Schema: application/json
required
object (DesiredPortDateTime)

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

desiredPortDate
required
string

The date you want the numbers to be ported in, in ISO format.

desiredPortTime
string

The time you want the numbers to be ported in.

desiredPortTimeZone
string

The time zone you want to use for the desired port time.

Enum Value Description
US/Eastern

US Eastern Timezone

US/Central

US Central Timezone

US/Mountain

US Mountain Timezone

US/Pacific

US Pacific Timezone

id
number

The unique identifier for the order

status
string (OrderStatus)
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 can not submit same numbers on a new order

CANCELED

The order is cancelled, either by the customer or by the system

customerOrderReference
string
Default: ""

Your reference you specified when creating the order

onDemandActivation
boolean
Default: false

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

Array of objects (Phone numbers)

The numbers for the order in e164 format

Array
phoneNumber
required
string <e164>
required
object (EndUser)

if specified will override the endUser for the order

required
object (PortOutItem)

if specified will override the endUser for the order

status
string
Default: "PENDING"
Enum Value Description
PENDING

The number is pending, and can be updated

CONFIRMED

The number is confirmed, and can not be updated but if onDemand is true it can be activated

REJECTED

The number is rejected, look at the rejectReason for more details it can be either its not portable or wrong port out info

ACTIVATED

The number is activated

CANCELED

The number is cancelled, either by the customer or by the system

EXCLUDED

The number is excluded from the order, look at the exclusionReason for more details

exclusionReason
string
Default: ""

If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.

exclusionTime
string <date-time>

If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.

countryCode
string

The country code of the number ISD code US, SE etc. At the moment only north american numbers are supported

activateTime
string

the time the number was activated UTC timezone

activateUser
string

The user that activated the number

RTC (object) or EST (object) or FAX (object) (VoiceConfiguration)
object (SmsConfiguration)

if specified will override the sms configuration for the order

object (Feature)
newPortOutPin
string
rejectReason
string

The reason the number was rejected

Array of objects
phoneNumberGroup
string
focDate
string <date-time>

Once the phone number has a firm order confirmation date, it will be returned as part of the phone number details.

Array of objects (OrderNote)

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

Array
note
string

The actual message

createdTime
createdBy
string
Array of objects (OrderDocumentBase)

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

Array
id
number
documentName
string
description
string
createdDate
string <date-time>

When the order was created

resellerName
string
Default: ""

This is requirement for canadian numbers only, we need to figure out what we expect here and where the customer can find this info

post/orders/portIns
Request samples
application/json
{
  • "desiredPortSchedule": {
    • "desiredPortDate": "2025-01-31",
    • "desiredPortTime": "10:00:00",
    • "desiredPortTimeZone": "US/Eastern"
    },
  • "phoneNumbers": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "id": 890192331,
  • "status": "PENDING",
  • "customerOrderReference": "123456",
  • "onDemandActivation": false,
  • "desiredPortSchedule": {
    • "desiredPortDate": "2025-01-31",
    • "desiredPortTime": "09:00:00",
    • "desiredPortTimeZone": "US/Eastern"
    },
  • "phoneNumbers": [
    • {
      }
    ],
  • "notes": [
    • {
      }
    ],
  • "documents": [
    • {
      }
    ],
  • "createdDate": "2019-08-24T14:15:22Z",
  • "resellerName": ""
}

List port-in orders

Retrieve a list of port-in based on the search parameters, you can also specify view here to get less detail

SecuritybasicAuth or bearerAuth
Request
query Parameters
orderId
number

Search by the ID of the order.

orderStatus
string (OrderStatus)

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 can not submit same numbers on a new order

CANCELED

The order is cancelled, either by the customer or by the system

customerOrderReference
string

The reference you specified when creating the order.

createdDateStart
string

Search by the created date. This query sets the start date of the search period. Date Format: yyyy-mm-dd.

createdDateEnd
string

Search by the created date. This query sets the end date of the search period. Date Format: yyyy-mm-dd.

phoneNumber
string

Search by a phone number.

focStartDate
string <date-time>

Search by the firm order confirmation. This query sets the start date of the search period. Date format: yyyy-mm-dd.

focEndDate
string <date-time>

Search by the firm order confirmation. This query sets the end date of the search period. Date format: yyyy-mm-dd.

pageSize
integer [ 1 .. 1000 ]

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.

page
string

The page you want to retrieve returned from a previous List request, if any

Responses
200

Successful operation

Response Schema: application/json
Array of objects (OrderListItem)
Array
id
number

The unique identifier for the order

status
string (OrderStatus)
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 can not submit same numbers on a new order

CANCELED

The order is cancelled, either by the customer or by the system

customerOrderReference
string
Default: ""

Your reference you specified when creating the order

createdDate
string <date-time>

When the order was created

phoneNumberQuantity
number

The number of phone numbers in the order, a helper property for you, this can also be done by and counting on the numbers collection

focQuantity
number

The number of phone numbers that are confirmed, a helper property for you, this can also be done by and counting on the numbers collection and filtering on status CONFIRMED

activatedQuantity
number

The number of phone numbers that are activated, The number of phone numbers that are confirmed, a helper property for you, this can also be done by and counting on the numbers collection and filtering on status COMPLETE

rejectedQuantity
number

The number of phone numbers that are rejected, This can be done by counting on the phoneNumbers collection and filtering on status REJECTED

excludedQuantity
number

The number of phone numbers that are activated, The number of phone numbers that are confirmed, a helper property for you, this can also be done by and counting on the numbers collection and filtering on status EXCLUDED

page
integer

Current page

totalPages
integer

Total number of pages.

pageSize
integer

Number of items per page.

totalItems
integer <int32>

Total size of the result.

get/orders/portIns
Request samples 
Response samples 
application/json
{
  • "orders": [
    • {
      }
    ],
  • "page": 0,
  • "totalPages": 0,
  • "pageSize": 0,
  • "totalItems": 0
}
Get  order Detail
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.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
orderId
required
number
Order Identifier


 
 Example:  897867
Responses 
200
Successful operation


Response Schema: application/json
required
object (DesiredPortDateTime) 
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


 
desiredPortDate
required
string
The date you want the numbers to be ported in, in ISO format.


 
desiredPortTime
string
The time you want the numbers to be ported in.


 
desiredPortTimeZone
string
The time zone you want to use for the desired port time.


 Enum Value Description
US/Eastern
US Eastern Timezone


US/Central
US Central Timezone


US/Mountain
US Mountain Timezone


US/Pacific
US Pacific Timezone


 
id
number
The unique identifier for the order


 
status
string (OrderStatus) 
 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 can not submit same numbers on a new order


CANCELED
The order is cancelled, either by the customer or by the system


 
customerOrderReference
string
 Default:  ""
Your reference you specified when creating the order


 
onDemandActivation
boolean
 Default:  false
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


 
Array of objects (Phone numbers) 
The numbers for the order in e164 format


 
 Array 
phoneNumber
required
string <e164> 
 
required
object (EndUser) 
if specified will override the endUser for the order


 
required
object (PortOutItem) 
if specified will override the endUser for the order


 
status
string
 Default:  "PENDING"
 Enum Value Description
PENDING
The number is pending, and can be updated


CONFIRMED
The number is confirmed, and can not be updated but if onDemand is true it can be activated


REJECTED
The number is rejected, look at the rejectReason for more details it can be either its not portable or wrong port out info


ACTIVATED
The number is activated


CANCELED
The number is cancelled, either by the customer or by the system


EXCLUDED
The number is excluded from the order, look at the exclusionReason for more details


 
exclusionReason
string
 Default:  ""
If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.


 
exclusionTime
string <date-time> 
If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.


 
countryCode
string
The country code of the number ISD code US, SE etc. At the moment only north american numbers are supported


 
activateTime
string
the time the number was activated UTC timezone


 
activateUser
string
The user that activated the number


 
RTC (object) or EST (object) or FAX (object) (VoiceConfiguration) 
 
object (SmsConfiguration) 
if specified will override the sms configuration for the order


 
object (Feature) 
 
newPortOutPin
string
 
rejectReason
string
The reason the number was rejected


 
Array of objects
 
phoneNumberGroup
string
 
focDate
string <date-time> 
Once the phone number has a firm order confirmation date, it will be returned as part of the phone number details.


 
Array of objects (OrderNote) 
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


 
 Array 
note
string
The actual message


 
createdTime
createdBy
string
 
Array of objects (OrderDocumentBase) 
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


 
 Array 
id
number
 
documentName
string
 
description
string
 
createdDate
string <date-time> 
When the order was created


 
resellerName
string
 Default:  ""
This is requirement for canadian numbers only, we need to figure out what we expect here and where the customer can find this info


 
get/orders/portIns/{orderId}
Request samples 
Response samples 
application/json
{
  • "id": 890192331,
  • "status": "PENDING",
  • "customerOrderReference": "123456",
  • "onDemandActivation": false,
  • "desiredPortSchedule": {
    • "desiredPortDate": "2025-01-31",
    • "desiredPortTime": "09:00:00",
    • "desiredPortTimeZone": "US/Eastern"
    },
  • "phoneNumbers": [
    • {
      }
    ],
  • "notes": [
    • {
      }
    ],
  • "documents": [
    • {
      }
    ],
  • "createdDate": "2019-08-24T14:15:22Z",
  • "resellerName": ""
}
Cancel Pending Order
This operation allows you to cancel an order in Pending status.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
orderId
required
number
Order Identifier


 
 Example:  897867
Responses 
200
Successful operation


delete/orders/portIns/{orderId}
Request samples 
Update port-in order
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


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
orderId
required
string
The unique identifier for the order.


 
Request Body schema: application/json
required
Update Pending Order


required
object (DesiredPortDateTime) 
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


 
desiredPortDate
required
string
The date you want the numbers to be ported in, in ISO format.


 
desiredPortTime
string
The time you want the numbers to be ported in.


 
desiredPortTimeZone
string
The time zone you want to use for the desired port time.


 Enum Value Description
US/Eastern
US Eastern Timezone


US/Central
US Central Timezone


US/Mountain
US Mountain Timezone


US/Pacific
US Pacific Timezone


 
customerOrderReference
string
 Default:  ""
Your reference you specified when creating the order


 
onDemandActivation
boolean
 Default:  false
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


 
Array of objects (Phone numbers) 
The numbers for the order in e164 format


 
 Array 
phoneNumber
required
string <e164> 
 
required
object (EndUser) 
if specified will override the endUser for the order


 
required
object (PortOutItem) 
if specified will override the endUser for the order


 
RTC (object) or EST (object) or FAX (object) (VoiceConfiguration) 
 
object (SmsConfiguration) 
if specified will override the sms configuration for the order


 
object (Feature) 
 
newPortOutPin
string
 
resellerName
string
 Default:  ""
This is requirement for canadian numbers only, we need to figure out what we expect here and where the customer can find this info


 
Responses 
200
Successful operation


Response Schema: application/json
required
object (DesiredPortDateTime) 
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


 
desiredPortDate
required
string
The date you want the numbers to be ported in, in ISO format.


 
desiredPortTime
string
The time you want the numbers to be ported in.


 
desiredPortTimeZone
string
The time zone you want to use for the desired port time.


 Enum Value Description
US/Eastern
US Eastern Timezone


US/Central
US Central Timezone


US/Mountain
US Mountain Timezone


US/Pacific
US Pacific Timezone


 
id
number
The unique identifier for the order


 
status
string (OrderStatus) 
 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 can not submit same numbers on a new order


CANCELED
The order is cancelled, either by the customer or by the system


 
customerOrderReference
string
 Default:  ""
Your reference you specified when creating the order


 
onDemandActivation
boolean
 Default:  false
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


 
Array of objects (Phone numbers) 
The numbers for the order in e164 format


 
 Array 
phoneNumber
required
string <e164> 
 
required
object (EndUser) 
if specified will override the endUser for the order


 
required
object (PortOutItem) 
if specified will override the endUser for the order


 
status
string
 Default:  "PENDING"
 Enum Value Description
PENDING
The number is pending, and can be updated


CONFIRMED
The number is confirmed, and can not be updated but if onDemand is true it can be activated


REJECTED
The number is rejected, look at the rejectReason for more details it can be either its not portable or wrong port out info


ACTIVATED
The number is activated


CANCELED
The number is cancelled, either by the customer or by the system


EXCLUDED
The number is excluded from the order, look at the exclusionReason for more details


 
exclusionReason
string
 Default:  ""
If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.


 
exclusionTime
string <date-time> 
If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion.


 
countryCode
string
The country code of the number ISD code US, SE etc. At the moment only north american numbers are supported


 
activateTime
string
the time the number was activated UTC timezone


 
activateUser
string
The user that activated the number


 
RTC (object) or EST (object) or FAX (object) (VoiceConfiguration) 
 
object (SmsConfiguration) 
if specified will override the sms configuration for the order


 
object (Feature) 
 
newPortOutPin
string
 
rejectReason
string
The reason the number was rejected


 
Array of objects
 
phoneNumberGroup
string
 
focDate
string <date-time> 
Once the phone number has a firm order confirmation date, it will be returned as part of the phone number details.


 
Array of objects (OrderNote) 
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


 
 Array 
note
string
The actual message


 
createdTime
createdBy
string
 
Array of objects (OrderDocumentBase) 
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


 
 Array 
id
number
 
documentName
string
 
description
string
 
createdDate
string <date-time> 
When the order was created


 
resellerName
string
 Default:  ""
This is requirement for canadian numbers only, we need to figure out what we expect here and where the customer can find this info


 
put/orders/portIns/{orderId}
Request samples 
application/json
{
  • "desiredPortSchedule": {
    • "desiredPortDate": "2025-01-31"
    }
}
Response samples 
application/json
{
  • "id": 890192331,
  • "status": "PENDING",
  • "customerOrderReference": "123456",
  • "onDemandActivation": false,
  • "desiredPortSchedule": {
    • "desiredPortDate": "2025-01-31",
    • "desiredPortTime": "09:00:00",
    • "desiredPortTimeZone": "US/Eastern"
    },
  • "phoneNumbers": [
    • {
      }
    ],
  • "notes": [
    • {
      }
    ],
  • "documents": [
    • {
      }
    ],
  • "createdDate": "2019-08-24T14:15:22Z",
  • "resellerName": ""
}
Add Order Note
This operation allows you to add a note to an existing order.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
orderId
required
number
Order Identifier


 
Request Body schema: application/json
required
Add Order Note


note
string
 
Responses 
200
Successful operation


Response Schema: application/json
id
number
 
note
string
 
post/orders/portIns/{orderId}/notes
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": 0,
  • "note": "string"
}
Add Order Document
This operation allows you to add a document to an existing order.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
orderId
required
number
Order Identifier


 
Request Body schema: application/json
required
Add Order Document


documentName
string
 
description
string
 
fileContent
string
Base64 encoded content representing the file contents.


 
Responses 
200
Successful operation, the file name/description would be returned, but the content would not be returned in the response.


Response Schema: application/json
id
number
 
documentName
string
 
description
string
 
post/orders/portIns/{orderId}/documents
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": 0,
  • "documentName": "string",
  • "description": "string"
}
Get document content
This operation allows you to retrieve specific document contents attached to an existing order.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
orderId
required
number
Order Identifier


 
documentId
required
string
Document content for


 
Responses 
200
Successful operation


Response Schema: application/json
documentId
number
 
id
number
 
documentName
string
 
description
string
 
fileContent
string
Base64 encoded content representing the file contents.


 
contentType
string
 
get/orders/{orderId}/documents/{documentId}
Request samples 
Response samples 
application/json
{
  • "documentId": 0,
  • "id": 0,
  • "documentName": "string",
  • "description": "string",
  • "fileContent": "string",
  • "contentType": "string"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.