Skip to contentSkip to navigationSkip to topbar
On this page

Port In Request API


This API allows you to submit a port in request for a set of phone numbers to Twilio. A Port In Request contains potentially many Port In Phone Numbers. So Port In Request allows to group assets shared across multiple phone numbers, but every phone number is independent of each other. For example, clients can use 1 LOA for all phone numbers in the same port in request. That LOA gets generated based on the authorized representative information in the port in request and other fields that are also shared for all phone numbers in that request. Paired with the Webhook APIs, and Port In Phone Number APIs, you should have visibility and access to handle basic errors within the port in process as well.


Limitations

limitations page anchor

Currently the Port In Request API has the following restrictions:


Property nameTypeRequiredDescriptionChild properties
port_in_request_sidSID<KW>Optional
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

urlstring<uri>Optional

The URL of this Port In request


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

notification_emailsarray[string]Optional

Additional emails to send a copy of the signed LOA to.


target_port_in_datestring<date>Optional

Target date to port the number. We cannot guarantee that this date will be honored by the other carriers, please work with Ops to get a confirmation of the firm order commitment (FOC) date. Expected format is ISO Local Date, example: ‘2011-12-03`. This date must be at least 7 days in the future for US ports and 10 days in the future for Japanese ports. (This value is only available for custom porting customers.)


target_port_in_time_range_startstringOptional

The earliest time that the port should occur on the target port in date. Expected format is ISO Offset Time, example: ‘10:15:00-08:00'. (This value is only available for custom porting customers.)


target_port_in_time_range_endstringOptional

The latest time that the port should occur on the target port in date. Expected format is ISO Offset Time, example: ‘10:15:00-08:00'. (This value is only available for custom porting customers.)


port_in_request_statusstringOptional

The status of the port in request. The possible values are: In progress, Completed, Expired, In review, Waiting for Signature, Action Required, and Canceled.


losing_carrier_informationobjectOptional

Details regarding the customer’s information with the losing carrier. These values will be used to generate the letter of authorization and should match the losing carrier’s data as closely as possible to ensure the port is accepted.


phone_numbersarrayOptional

documentsarray[string]Optional

List of document SIDs for all phone numbers included in the port in request. At least one document SID referring to a document of the type Utility Bill is required.


date_createdstring<date-time>Optional

phone_number properties

phone_number-properties page anchor
FieldsData TypeRequiredCountryDescription
phone_numberStringYesAllPhone number to be ported. This must be in E164 format.
pinStringNoAllIf the phone number is mobile, this field is mandatory to process a porting request. A PIN is the security tool designed to prevent unauthorized use of the SIM card (chip) of a phone number. It should be provided by the losing carrier.

losing_carrier_information properties

losing_carrier_information-properties page anchor

The "losing carrier" is the losing carrier that you are porting away from. Here are the properties in the losing_carrier_information field.

FieldsData TypeRequiredCountryDescription
customer_typeStringYesAllThe type of customer account in the losing carrier. This should either be: Individual or Business.
customer_nameStringYesAllCustomer name as it is registered with the losing carrier. This can be an individual or a business name depending on the customer type selected.
account_numberStringNoAllCustomer account number in the carrier who owns numbers to be ported. It's mandatory for US local numbers.
account_telephone_numberStringNoAllMaster number used by carriers to identify an account with many phone numbers. It's mandatory for US local numbers.
address_sidStringNoAllIf you already have an Address SID that represents the address needed for the LOA, you can provide an Address SID instead of providing the address object in the request body. This will copy the address into the port in request. If changes are made to the Address SID after port in request creation, those changes will not be reflected in the port in request.
addressObjectNoAllThe customer's billing address with the losing carrier. It must match the address they have registered with the losing carrier!
address.streetStringNoAllThe street address, ex: 101 Spear St
address.street_2StringNoAllThe building information, ex : 5th floor
address.cityStringNoAllThe city name, ex: San Francisco
address.stateStringNoAllThe state name, ex: CA or California Note this should match the losing carrier's information exactly. So if they spell out the entire state's name instead of abbreviating it, please do so.
address.zipStringNoAllThe zip code, ex: 94105
address.countryStringNoAllThe country, ex: USA
authorized_representativeStringYesAllThe first and last name of the person listed with the losing carrier who is authorized to make changes on the account.
authorized_representative_emailStringYesAllEmail address of the person (owner of the number) who will sign the letter of authorization for the port in request. This email address should belong to the person named in as the authorized representative.
authorized_representative_katakanaStringNoJapanThis field is required only for Japanese ports, more details to come.
subscription_rightStringNoJapanThis field is required only for Japanese ports, more details to come.
pre_adjustment_articleStringNoJapanThis field is required only for Japanese ports, more details to come.
mnp_articleStringNoJapanThis field is required only for Japanese ports, more details to come.
losing_carrier_nameStringNoJapanThis field is required only for Japanese ports, more details to come.

Create a Port In Request

create-a-port-in-request page anchor

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

Create Port In RequestLink to code sample: Create Port In Request
1
$ curl --location 'https://numbers.twilio.com/v1/Porting/PortIn' \
2
--header 'Content-Type: application/json' \
3
--header 'Authorization: Basic {{YOUR TOKEN HERE}}’ \
4
--data-raw '{
5
"account_sid": "AC5d169368692aa8ab93638f0efb556ba3",
6
"target_port_in_date": "2024-10-31",
7
"target_port_in_time_range_start": "11:00",
8
"target_port_in_time_range_end": "13:00",
9
"notification_emails": ["bar@twilio.com", "foo@twilio.com"],
10
"losing_carrier_information": {
11
"customer_type": "Business",
12
"customer_name": "FooBar Inc.",
13
"account_number": "Test123",
14
"account_telephone_number": "+16175551212",
15
"authorized_representative": "John Smith",
16
"authorized_representative_email": "foo@twilio.com",
17
"address_sid": null,
18
"address": {
19
"street": "101 Spear St",
20
"street_2": "5th floor",
21
"city": "San Francisco",
22
"state": "CA",
23
"zip": "94105",
24
"country": "US"
25
}
26
},
27
"phone_numbers": [
28
{
29
"phone_number": "+13802075834",
30
"pin": null
31
}
32
],
33
"documents": [
34
"RD0f36b9a5a6a700fb5949ea9959d041c3"
35
]
36
}'

Output

1
{
2
"account_sid": "AC5d169368692aa8ab93638f0efb556ba3",
3
"target_port_in_date": "2024-10-31",
4
"port_in_request_sid": "KW5096cf8e95c21761161c4f0388074b3a",
5
"port_in_request_status": "In Progress",
6
"target_port_in_time_range_start": "11:00",
7
"target_port_in_time_range_end": "13:00",
8
"date_created": "2024-05-03T16:13:10Z",
9
"notification_emails": ["bar@twilio.com", "foo@twilio.com"],
10
"losing_carrier_information": {
11
"customer_type": "Business",
12
"customer_name": "FooBar Inc.",
13
"account_number": "Test123",
14
"account_telephone_number": "+16175551212",
15
"authorized_representative": "John Smith",
16
"authorized_representative_email": "foo@twilio.com",
17
"address_sid": null,
18
"address": {
19
"street": "101 Spear St",
20
"street_2": "5th floor",
21
"city": "San Francisco",
22
"state": "CA",
23
"zip": "94105",
24
"country": "US"
25
},
26
"authorized_representative_katakana": null,
27
"subscription_right": null,
28
"pre_adjustment_article": null,
29
"mnp_article": null,
30
"losing_carrier_name": null
31
},
32
"phone_numbers": [
33
{
34
"phone_number": "+13503331359",
35
"portable": true,
36
"rejection_reason": null,
37
"port_in_phone_number_status": "in_review",
38
"rejection_reason_code": null,
39
"not_portability_reason": null,
40
"port_in_phone_number_sid": "PUf0e8205043b2a805a1672eb137043afd",
41
"not_portability_reason_code": null
42
}
43
],
44
"documents": [
45
"RD0f36b9a5a6a700fb5949ea9959d041c3"
46
]
47
}
HTTP Status CodeResponseNext Steps
400{
"code": 400,
"message": "phoneNumbers: size must be between 1 and 1000",
"more_info": "https://www.twilio.com/docs/errors/400",
"status": 400
}
Review the message value to determine what fields you need to correct. After correcting the values in your request, try to send the request again.
400{
"code": 400,
"message": "Invalid documents",
"more_info": "https://www.twilio.com/docs/errors/400",
"status": 400
}
Confirm that you provided at least one document SIDs in the documents field. Please note that at least one of the provided document SIDs must refer to a document of the type "Utility Bill"
403{
"code": 20403,
"message": "Account lacks permission to access the API (possibly suspended or closed)",
"more_info": "https://www.twilio.com/docs/errors/20403",
"status": 403
}
This indicates you do not have access to port numbers into this account.
Confirm you've got the correct Account Sid and try again.
500{
"code": 20500,
"message": "An internal server error has occurred",
"more_info": "https://www.twilio.com/docs/errors/20500",
"status": 500
}
This indicates there was an error within Twilio while trying to create the Port In request. Please try again and contact support if the issue persists.

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

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
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchPortingPortIn() {
11
const portingPortIn = await client.numbers.v1
12
.portingPortIns("KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.fetch();
14
15
console.log(portingPortIn.portInRequestSid);
16
}
17
18
fetchPortingPortIn();

Output

1
{
2
"port_in_request_sid": "KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"url": "https://numbers.twilio.com/v1/Porting/PortIn/KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"notification_emails": [
6
"user@domain.com"
7
],
8
"target_port_in_date": "2023-09-10",
9
"target_port_in_time_range_start": "10:00:00+01:00",
10
"target_port_in_time_range_end": "20:00:00+01:00",
11
"port_in_request_status": "pending",
12
"date_created": "2023-09-10T06:52:21Z",
13
"losing_carrier_information": {
14
"customer_type": "Business/Individual",
15
"customer_name": "Customer name for carrier",
16
"authorized_representative": "John Smith",
17
"authorized_representative_email": "signer@domain.com",
18
"account_number": "123456",
19
"account_telephone_number": "+133232323",
20
"address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21
"address": {
22
"street": "Your Street",
23
"street_2": "Other Street or null",
24
"city": "City",
25
"state": "State",
26
"zip": "000000",
27
"country": "US"
28
}
29
},
30
"phone_numbers": [
31
{
32
"phone_number": "+16175551212",
33
"pin": "123456",
34
"portable": true,
35
"not_portability_reason": "string",
36
"not_portability_reason_code": 0,
37
"port_in_phone_number_sid": "PUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
38
"port_in_phone_number_status": "In Review",
39
"port_date": "2023-09-17T00:00:00Z"
40
}
41
],
42
"documents": [
43
"ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
44
]
45
}

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

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

To cancel a Port In Request you can send a DELETE request to the API. This will cancel the porting request and all associated phone number requests. Twilio is only able to accept cancellations that occur more than 72 hrs before the port in date.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function deletePortingPortIn() {
11
await client.numbers.v1
12
.portingPortIns("KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.remove();
14
}
15
16
deletePortingPortIn();

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.