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 UpdatedWebhook

This operation allows you to get a webhook when an order is updated. This is a webhook that will be called when an order is updated, it will contain the order and the status of the order.

SecuritybasicAuth or bearerAuth

Request

Request Body schema: application/json

event

string

Default: "ORDER_UPDATED"

The event that triggered the webhook

Value	Description
ORDER_UPDATED	The order was updated it can be status or any other updates to a pending order

orderId

string

The order id that was updated

object (OrderBaseItem)

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

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	string UTC iso https://www.ietf.org/rfc/rfc3339.txt
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

Request samples

Payload

application/json

{"type": "ORDER_UPDATED",
"orderId": "897867",
"order": {"id": 897867,
"customerOrderReference": "123456",
"desiredPortSchedule": {"desiredPortDate": "2024-09-24",
"desiredPortTime": "09:00:00Z"
},
"status": "PENDING",
"onDemandActivation": false,
"phoneNumbers": [{"phoneNumber": "+12345678901",
"portOutInfo": {"existingPortOutPin": "1234"
},
"endUser": {"name": "John Doe",
"streetName": "Main St",
"streetNum": "123",
"city": "Anytown",
"state": "NY",
"zipCode": "12345"
},
"voiceConfiguration": {"type": "EST",
"trunkId": "123456"
}
}
]
}
}

Number activatedWebhook

At least one number on the port order was activated

SecuritybasicAuth or bearerAuth

Request

Request Body schema: application/json

event

string

Default: "NUMBERS_ACTIVATED"

The event that triggered the webhook

Enum Value	Description
ORDER_UPDATED	The order was updated it can be status or any other updates to a pending order
NUMBERS_ACTIVATED	at least one number was activated
NUMBERS_CONFIRMED	At least one number was confirmed
NUMBERS_REJECTED	At least one number was rejected
NEW_ORDER_NOTE	A new note was added to the order

orderId

string

The order id that was updated

Array of objects (PhoneNumberMinItem)

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.

Request samples

Payload

application/json

{"type": "NUMBERS_ACTIVATED",
"orderId": 897867,
"phoneNumbers": [{"phoneNumber": "+12345678901",
"status": "Activated",
"activatedDate": "2024-09-24T12:00:00Z"
}
]
}

Number confirmedWebhook

At least one number on the port order was confirmed, this means that the number is ready to be activated if onDemandActivation was set to true or if it will be activated at the specified confirmation date

SecuritybasicAuth or bearerAuth

Request

Request Body schema: application/json

event

string

Default: "NUMBERS_CONFIRMED"

The event that triggered the webhook

Enum Value	Description
ORDER_UPDATED	The order was updated it can be status or any other updates to a pending order
NUMBERS_ACTIVATED	at least one number was activated
NUMBERS_CONFIRMED	At least one number was confirmed
NUMBERS_REJECTED	At least one number was rejected
NEW_ORDER_NOTE	A new note was added to the order

orderId

string

The order id that was updated

Array of objects (PhoneNumberMinItem)

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.

Request samples

Payload

application/json

{"type": "NUMBERS_CONFIRMED",
"orderId": 897867,
"phoneNumbers": [{"phoneNumber": "+12345678901",
"status": "Confirmed",
"confirmedDate": "2024-09-24T12:00:00Z"
}
]
}

Number RejectedWebhook

At least one number on the port order was rejected, look at rejected reasons for more details on what went wrong

SecuritybasicAuth or bearerAuth

Request

Request Body schema: application/json

event

string

Default: "NUMBERS_REJECTED"

The event that triggered the webhook

Enum Value	Description
ORDER_UPDATED	The order was updated it can be status or any other updates to a pending order
NUMBERS_ACTIVATED	at least one number was activated
NUMBERS_CONFIRMED	At least one number was confirmed
NUMBERS_REJECTED	At least one number was rejected
NEW_ORDER_NOTE	A new note was added to the order

orderId

string

The order id that was updated

Array of objects (PhoneNumberMinItem)

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.

Request samples

Payload

application/json

{"type": "NUMBERS_REJECTED",
"orderId": 897867,
"phoneNumbers": [{"phoneNumber": "+12345678901",
"status": "Confirmed",
"confirmedDate": "2024-09-24T12:00:00Z"
}
]
}

Note added to orderWebhook

A note was added to the order either by Sinch or you

SecuritybasicAuth or bearerAuth

Request

Request Body schema: application/json

event

string

Default: "NEW_ORDER_NOTE"

The event that triggered the webhook

Enum Value	Description
ORDER_UPDATED	The order was updated it can be status or any other updates to a pending order
NUMBERS_ACTIVATED	at least one number was activated
NUMBERS_CONFIRMED	At least one number was confirmed
NUMBERS_REJECTED	At least one number was rejected
NEW_ORDER_NOTE	A new note was added to the order

orderId

string

The order id that was updated

note

string

The note that was added

Request samples

Payload

application/json

{"type": "NEW_ORDER_NOTE",
"orderId": 897867,
"note": "This is a note"
}

Security Privacy Legal & Compliance Cookie Statement