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.

Use the Portability resource to check if you can port a number to Twilio before you start the porting process. This resource also provides details about why you can't port a number or what manual actions you need to take to facilitate porting that number.

PhoneNumber Properties

Property nameTypeRequiredPIIDescriptionChild 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 HTTP 400 (BAD REQUEST) response body includes one of the following portability reason codes in the not_portable_reason and not_portable_reason_code properties.

Status code	Portability reason	Description
22131	`ALREADY_IN_THE_TARGET_ACCOUNT`	The phone number already exists on your Twilio account or is currently being ported to your Twilio account.
22132	`ALREADY_IN_TWILIO_DIFFERENT_OWNER`	The 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`	The phone number already exists in one of your accounts or is currently being ported to one of your Twilio accounts. Learn more about moving Twilio phone numbers to another Twilio account in the Twilio Help Center.
22130	`UNSUPPORTED`	Twilio doesn't support the phone number's country, rate center, or carrier.
22133	`MANUAL_PORTING_AVAILABLE`	You can't port the phone number 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`	The portability API requires E.164 format for numbers. Resend the request with an E.164 formatted phone number.
22171	`MISSING_REQUIRED_FIELDS`	The phone number requires additional fields to be ported, but you haven't provided these fields.
22135	`ERROR_INTERNAL_SERVER_ERROR`	Internal error occurred while determining the portability of this number. Try the request again.
20003	`UNAUTHORIZED`	The account provided isn't valid or you don't 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 you use to call the API.

This 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 looks similar to this JSON example. The portable Boolean indicates whether you can port the phone number to Twilio. The pin_and_account_number_required field 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 isn't portable, the response body looks similar to this JSON example. The portable Boolean is false. Both the not_portable_reason_code and not_portable_reason fields provide additional details about why you can't port the phone number.

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}