Skip to content Skip to navigation Skip to topbar

On this page

Port In Phone Numbers API

The following APIs allow actions on a single phone number within a port in request. You can find the SID of a port in phone number from the GET Port In Request API.

PhoneNumber Properties

Property nameTypeRequiredDescriptionChild properties

port_in_request_sidSID<KW>Optional

Not PII

The unique identifier for the port in request that this phone number is associated with.

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

phone_number_sidSID<PU>Optional

Not PII

The unique identifier for this phone number associated with this port in request.

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

urlstring<uri>Optional

Not PII

URL reference for this resource.

account_sidSID<AC>Optional

Not PII

Account Sid or subaccount where the phone number(s) will be Ported.

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

phone_number_typestringOptional

Not PII

The number type of the phone number. This can be: toll-free, local, mobile or unknown. This field may be null if the number is not portable or if the portability for a number has not yet been evaluated.

date_createdstring<date-time>Optional

Not PII

The timestamp for when this port in phone number was created.

countrystring<iso-country-code>Optional

Not PII

The ISO country code that this number is associated with. This field may be null if the number is not portable or if the portability for a number has not yet been evaluated.

missing_required_fieldsbooleanOptional

Not PII

Indicates if the phone number is missing required fields such as a PIN or account number. This field may be null if the number is not portable or if the portability for a number has not yet been evaluated.

last_updatedstring<date-time>Optional

Not PII

Timestamp indicating when the Port In Phone Number resource was last modified.

phone_numberstring<phone-number>Optional

Not PII

Phone number to be ported. This will be in the E164 Format.

portablebooleanOptional

Not PII

If the number is portable by Twilio or not. This field may be null if the number portability has not yet been evaluated. If a number is not portable reference the not_portability_reason_code and not_portability_reason fields for more details

not_portability_reasonstringOptional

Not PII

The not portability reason code description. This field may be null if the number is portable or if the portability for a number has not yet been evaluated.

not_portability_reason_codeintegerOptional

Not PII

The not portability reason code. This field may be null if the number is portable or if the portability for a number has not yet been evaluated.

port_in_phone_number_statusstringOptional

Not PII

The status of the port in phone number.

port_out_pinintegerOptional

Not PII

The pin required by the losing carrier to do the port out.

rejection_reasonstringOptional

Not PII

The description of the rejection reason provided by the losing carrier. This field may be null if the number has not been rejected by the losing carrier.

rejection_reason_codeintegerOptional

Not PII

The code for the rejection reason provided by the losing carrier. This field may be null if the number has not been rejected by the losing carrier.

port_datestring<date-time>Optional

Not PII

The timestamp the phone number will be ported. This will only be set once a port date has been confirmed. Not all carriers can guarantee a specific time on the port date. Twilio will try its best to get the port completed by this time on the port date. Please subscribe to webhooks for confirmation on when a port has actually been completed.

Fetch a Port In Phone Number

GET https://numbers.twilio.com/v1/Porting/PortIn/{PortInRequestSid}/PhoneNumber/{PhoneNumberSid}

Path parameters

Property nameTypeRequiredPIIDescription

PortInRequestSidSID<KW>required

Not PII

The SID of the Port In request. This is a unique identifier of the port in request.

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

PhoneNumberSidSID<PU>required

Not PII

The SID of the Phone number. This is a unique identifier of the phone number.

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

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 fetchPortingPortInPhoneNumber() {
11  const portingPortInPhoneNumber = await client.numbers.v1
12    .portingPortInPhoneNumber(
13      "KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "PUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
15    )
16    .fetch();
17
18  console.log(portingPortInPhoneNumber.portInRequestSid);
19}
20
21fetchPortingPortInPhoneNumber();

Output

1{
2  "port_in_request_sid": "KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "phone_number_type": "LOCAL",
5  "date_created": "2024-04-10T06:52:21Z",
6  "country": "US",
7  "missing_required_fields": false,
8  "last_updated": "2024-03-12T06:52:21Z",
9  "phone_number": "+15024953384",
10  "portable": true,
11  "not_portability_reason": "ALREADY_IN_TWILIO_DIFFERENT_OWNER",
12  "not_portability_reason_code": 22132,
13  "port_in_phone_number_status": "in_review",
14  "phone_number_sid": "PUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "port_out_pin": 1234,
16  "rejection_reason": null,
17  "rejection_reason_code": null,
18  "port_date": "2024-05-17T00:00:00Z",
19  "url": "https://numbers.twilio.com/v1/Porting/PortIn/KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumber/PUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
20}

Delete a Port In Phone Number

DELETE https://numbers.twilio.com/v1/Porting/PortIn/{PortInRequestSid}/PhoneNumber/{PhoneNumberSid}

Make a DELETE request to this API endpoint to cancel a single phone number Port In requesr.

There are some restrictions on when you can cancel the port of a phone number. Twilio is only able to accept cancellations that occur more than 72 hours before the port in date.

Path parameters

Property nameTypeRequiredPIIDescription

PortInRequestSidSID<KW>required

Not PII

The SID of the Port In request. This is a unique identifier of the port in request.

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

PhoneNumberSidSID<PU>required

Not PII

The SID of the Port In request phone number. This is a unique identifier of the phone number.

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

Delete 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 deletePortingPortInPhoneNumber() {
11  await client.numbers.v1
12    .portingPortInPhoneNumber(
13      "KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "PUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
15    )
16    .remove();
17}
18
19deletePortingPortInPhoneNumber();

Errors

An HTTP 201 response status code indicates an accepted cancellation request. Unsuccessful requests have the following error codes:

HTTP Status Code	Next Steps
404	The requested port in phone number does not exist on your account. Check that you have the correct port in request SID. Note all Port In Request SIDs should begin with `KW`.
500	There was an error within Twilio while trying to cancel the port in request. Please try again and contact support if the issue persists.