Skip to content Skip to navigation Skip to topbar

On this page

PortIn PhoneNumber subresource

(new)

Public Beta

The Porting API is 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 PhoneNumber subresource represents a single phone number within a port-in request. PhoneNumber is a subresource of the PortIn resource. You can get the phoneNumberSid of a phone number by fetching a port-in request.

PhoneNumber Properties

Property nameTypeRequiredDescriptionChild properties

portInRequestSidSID<KW>

Optional

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

phoneNumberSidSID<PU>

Optional

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

URL reference for this resource.

accountSidSID<AC>

Optional

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

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

phoneNumberTypestring

Optional

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.

dateCreatedstring<date-time>

Optional

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

countrystring<iso-country-code>

Optional

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.

missingRequiredFieldsboolean

Optional

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.

lastUpdatedstring<date-time>

Optional

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

phoneNumberstring<phone-number>

Optional

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

portableboolean

Optional

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

notPortabilityReasonstring

Optional

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.

notPortabilityReasonCodeinteger

Optional

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.

portInPhoneNumberStatusstring

Optional

The status of the port in phone number.

portOutPininteger

Optional

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

rejectionReasonstring

Optional

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.

rejectionReasonCodeinteger

Optional

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.

portDatestring<date-time>

Optional

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.

Every phone number in a port-in request has its own status. To learn more about the possible statuses, see the list of statuses.

Fetch a phone number from a port-in request

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

Path parameters

Property nameTypeRequiredPIIDescription

portInRequestSidSID<KW>

required

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

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();

Response

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 phone number from a port-in request

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

Make a DELETE request to this endpoint to cancel a single phone number in a port-in request.

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

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

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