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.
Currently the Port In Request API has the following restrictions:
The SID of the Port In request. This is a unique identifier of the port in request.
^KW[0-9a-fA-F]{32}$Min length: 34Max length: 34Account Sid or subaccount where the phone number(s) will be Ported
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34Additional emails to send a copy of the signed LOA to.
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.)
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.)
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.)
The status of the port in request. The possible values are: In progress, Completed, Expired, In review, Waiting for Signature, Action Required, and Canceled.
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.
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.
| Fields | Data Type | Required | Country | Description |
|---|---|---|---|---|
phone_number | String | Yes | All | Phone number to be ported. This must be in E164 format. |
pin | String | No | All | If 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. |
The "losing carrier" is the losing carrier that you are porting away from. Here are the properties in the losing_carrier_information field.
| Fields | Data Type | Required | Country | Description |
|---|---|---|---|---|
customer_type | String | Yes | All | The type of customer account in the losing carrier. This should either be: Individual or Business. |
customer_name | String | Yes | All | Customer 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_number | String | No | All | Customer account number in the carrier who owns numbers to be ported. It's mandatory for US local numbers. |
account_telephone_number | String | No | All | Master number used by carriers to identify an account with many phone numbers. It's mandatory for US local numbers. |
address_sid | String | No | All | If 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. |
address | Object | No | All | The customer's billing address with the losing carrier. It must match the address they have registered with the losing carrier! |
address.street | String | No | All | The street address, ex: 101 Spear St |
address.street_2 | String | No | All | The building information, ex : 5th floor |
address.city | String | No | All | The city name, ex: San Francisco |
address.state | String | No | All | The 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.zip | String | No | All | The zip code, ex: 94105 |
address.country | String | No | All | The country, ex: USA |
authorized_representative | String | Yes | All | The first and last name of the person listed with the losing carrier who is authorized to make changes on the account. |
authorized_representative_email | String | Yes | All | Email 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_katakana | String | No | Japan | This field is required only for Japanese ports, more details to come. |
subscription_right | String | No | Japan | This field is required only for Japanese ports, more details to come. |
pre_adjustment_article | String | No | Japan | This field is required only for Japanese ports, more details to come. |
mnp_article | String | No | Japan | This field is required only for Japanese ports, more details to come. |
losing_carrier_name | String | No | Japan | This field is required only for Japanese ports, more details to come. |
Path: GET https://numbers.twilio.com/v1/Porting/PortIn/{PortInRequestSid}
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": null31}32],33"documents": [34"RD0f36b9a5a6a700fb5949ea9959d041c3"35]36}'
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": null31},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": null42}43],44"documents": [45"RD0f36b9a5a6a700fb5949ea9959d041c3"46]47}
| HTTP Status Code | Response | Next 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}The SID of the Port In request. This is a unique identifier of the port in request.
^KW[0-9a-fA-F]{32}$Min length: 34Max length: 341// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchPortingPortIn() {11const portingPortIn = await client.numbers.v112.portingPortIns("KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.fetch();1415console.log(portingPortIn.portInRequestSid);16}1718fetchPortingPortIn();
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}The SID of the Port In request. This is a unique identifier of the port in request.
^KW[0-9a-fA-F]{32}$Min length: 34Max length: 34To 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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deletePortingPortIn() {11await client.numbers.v112.portingPortIns("KWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.remove();14}1516deletePortingPortIn();