Portability resource

(new)

Public Beta

The Porting API is are in Public Beta. The information in this document could change. We might add or update features before the product becomes Generally Available. Beta products don't have a Service Level Agreement (SLA). Learn more about beta product support.

The Portability resource allows you to check if a number can be ported to Twilio before starting the porting process. This resource also provides details about why a number cannot be ported or if manual actions are needed to facilitate the porting of that number.

PhoneNumber Properties

Property nameTypeRequiredDescriptionChild properties

phoneNumberstring<phone-number>

Optional

PII MTL: 0 days

The phone number which portability is to be checked. Phone numbers are in E.164 format (e.g. +16175551212).

accountSidSID<AC>

Optional

Not PII

Account Sid that the phone number belongs to in Twilio. This is only returned for phone numbers that already exist in Twilio’s inventory and belong to your account or sub account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

portableboolean

Optional

Not PII

Boolean flag indicates if the phone number can be ported into Twilio through the Porting API or not.

pinAndAccountNumberRequiredboolean

Optional

Not PII

Indicates if the port in process will require a personal identification number (PIN) and an account number for this phone number. If this is true you will be required to submit both a PIN and account number from the losing carrier for this number when opening a port in request. These fields will be required in order to complete the port in process to Twilio.

notPortableReasonstring

Optional

Not PII

Reason why the phone number cannot be ported into Twilio, null otherwise.

notPortableReasonCodeinteger

Optional

Not PII

The Portability Reason Code for the phone number if it cannot be ported into Twilio, null otherwise.

numberTypeenum<string>

Optional

Not PII

The type of the requested phone number. One of LOCAL, UNKNOWN, MOBILE, TOLL-FREE.

Possible values:

LOCALUNKNOWNMOBILETOLL-FREE

countrystring<iso-country-code>

Optional

Not PII

Country the phone number belongs to.

urlstring<uri>

Optional

Not PII

This is the url of the request that you're trying to reach out to locate the resource.

Not portable reason codes

When Twilio can't port a phone number, the response body of the HTTP 400 (BAD REQUEST) includes one of the following portability reason codes within the not_portable_reason and not_portable_reason_code properties.

Status code	Portability reason	Description
22131	`ALREADY_IN_THE_TARGET_ACCOUNT`	Phone number already exists on your Twilio account or is currently being ported into your Twilio account.
22132	`ALREADY_IN_TWILIO_DIFFERENT_OWNER`	Phone number already exists on another Twilio account. Learn more about moving Twilio phone numbers to another Twilio account in the Twilio Help Center.
22136	`ALREADY_IN_ONE_OF_YOUR_TWILIO_ACCOUNTS`	Phone number already exists in one of your accounts or is currently being ported into one of your Twilio accounts. Learn more about moving Twilio phone numbers to another Twilio account in the Twilio Help Center.
22130	`UNSUPPORTED`	Phone number is in a country, rate center, or on a carrier that is not supported by Twilio.
22133	`MANUAL_PORTING_AVAILABLE`	The phone number cannot be ported using the Twilio porting API. If the number is a US phone number, open a porting request through the Console. Learn more about porting a US phone number to Twilio in the Twilio Help Center. Otherwise, create a support ticket to port in a phone number from another country. Learn more about the international porting process in the Twilio Help Center.
22102	`INVALID_PHONE_NUMBER`	E.164 format is required for numbers in the portability API. Resend the request with an E.164 formatted phone number.
22171	`MISSING_REQUIRED_FIELDS`	Phone number requires additional fields to be ported and these have not been provided.
22135	`ERROR_INTERNAL_SERVER_ERROR`	Internal error determining the portability of this number. Try the request again.
20003	`UNAUTHORIZED`	The account provided is not valid or you do not have access to the provided account in the query parameter `target_account_sid`.

Check Portability

GET https://numbers.twilio.com/v1/Porting/Portability/PhoneNumber/{PhoneNumber}

To check the portability of a single phone number with the Portability resource, send a GET request. Replace {phone_number} with your E.164 formatted phone number and {target_account_sid} with the destination Account SID, if it differs from the account used to call the API.

The following example shows how to check portability using a curl command:

1curl --location 'https://numbers.twilio.com/v1/Porting/Portability/PhoneNumber/{phone_number}?TargetAccountSid={target_account_sid}'
2-u "Account_Sid:Access_token"

Path parameters

Property nameTypeRequiredPIIDescription

phoneNumberstring<phone-number>

required

PII MTL: 0 days

Phone number to check portability in e164 format.

Query parameters

Property nameTypeRequiredPIIDescription

targetAccountSidSID<AC>

Optional

Not PII

Account Sid to which the number will be ported. This can be used to determine if a sub account already has the number in its inventory or a different sub account. If this is not provided, the authenticated account will be assumed to be the target account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

addressSidSID<AD>

Optional

Not PII

Address Sid of customer to which the number will be ported.

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34

Example Portability responses

Portable phone number response

For a portable phone number, the response body will look similar to the following JSON example. The portable Boolean indicates whether or not the phone number can be ported into Twilio. The pin_and_account_number_required field that indicates if the phone number requires a PIN from the losing carrier as part of the porting process.

1{
2   "phone_number": "YOUR_NUMBER",
3   "portable": true,
4   "url": "https://numbers.twilio.com/v1/Porting/Portability/PhoneNumber/YOUR_NUMBER",
5   "country": "US",
6   "not_portable_reason": null,
7   "account_sid": null,
8   "pin_and_account_number_required": false,
9   "not_portable_reason_code": null,
10   "number_type": "LOCAL"
11}

Not portable phone number response

For a phone number that is not portable, the response body will look similar to the following JSON example. The portable Boolean is false. Both the not_portable_reason_code and not_portable_reason fields provide additional details about why the phone number is not portable.

1{
2   "phone_number": "YOUR_NUMBER",
3   "portable": false,
4   "url": "https://numbers.twilio.com/v1/Porting/Portability/PhoneNumber/YOUR_NUMBER",
5   "country": "CO",
6   "not_portable_reason": "UNSUPPORTED",
7   "account_sid": null,
8   "pin_and_account_number_required": true,
9   "not_portable_reason_code": 22130,
10   "number_type": "UNKNOWN"
11}

Fetch a PhoneNumber

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchPortingPortability() {
11  const portingPortability = await client.numbers.v1
12    .portingPortabilities("+14155552344")
13    .fetch();
14
15  console.log(portingPortability.phoneNumber);
16}
17
18fetchPortingPortability();

Response

1{
2  "phone_number": "+14155552344",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
4  "portable": false,
5  "pin_and_account_number_required": false,
6  "not_portable_reason": "MANUAL_PORTING_AVAILABLE",
7  "not_portable_reason_code": 22133,
8  "number_type": "TOLL-FREE",
9  "country": "US",
10  "url": "https://numbers.twilio.com/v1/Porting/Portability/PhoneNumber/+18001234567"
11}