Skip to content Skip to navigation Skip to topbar

On this page

Portability API

The portability API allows you to check if a number can be ported to Twilio before starting the porting process. This API 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

phone_numberstring<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).

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

pin_and_account_number_requiredboolean

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.

not_portable_reasonstring

Optional

Not PII

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

not_portable_reason_codeinteger

Optional

Not PII

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

number_typeenum<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

Below are the possible portability reason codes within the response body of an HTTP 400 (BAD REQUEST) that could be returned in 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. See this support page for more information on how to move the line to your account.
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. If needed, see this support page for more information on how to move the line to a different subaccount.
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, please open a porting request through the Console. See this support page for more information on US porting. Otherwise create a support ticket to port in a phone number from another country. See this support page for more information on international porting.
22102	`INVALID_PHONE_NUMBER`	E.164 format is required for numbers in the portability API. Please resend the request with an e164 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, please 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 request in the Portability API, you can send a GET request. Replace {phone_number} with your phone number in e164 format and {target_account_sid} with the Account SID for the account where you want to port a number, if it's different to the account used to call the API.

Below is a code example 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 below JSON. The portable Boolean indicates whether or not the phone number can be ported into Twilio. Also note the pin_and_account_number_required field that indicates if the phone number will require 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 below JSON. The portable Boolean will be false. Both the not_portable_reason_code and not_portable_reason fields will also be set in this case indicating additional details on 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();

Output

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}