REST API: Porting Phone Numbers

The REST API to port phone numbers to Twilio has the following key resources:

  1. The Port Orders instance resource represents a single port request comprising the phone number that the customer wishes to port to Twilio.
  2. The Port LOAs instance resource represents a single electronic Letter of Authorization (LOA) document that authorizes Twilio to port one or more phone numbers to Twilio on behalf of the customer requesting the port. This instance resource is automatically created using the information that was submitted to Twilio when creating the corresponding Port Orders instance resource.
  3. The Port Orders list resource represents the list of all phone numbers that are associated with a Twilio account or subaccount, identified by an Account SID, and are in the process of porting to Twilio.

Starting a new port request with Twilio by issuing POST to the Port Orders list resource creates corresponding Port Orders and Port LOAs instance resources.

Port Orders Instance Resource

The Port Orders instance resource represents a single port request comprising the phone number that the customer wishes to port to Twilio.

リソース URI

preview.twilio.com/porting/PortOrders/{PortOrderSid}

リソースのプロパティ

プロパティ 説明
sid このリソースを一意に識別する 34 文字の文字列です。
番号 Porting phone number in this resource. This must be in E.164 format, e.g., +16175551212.
friendly_name A 64 character string that is a human readable text that describes this resource. By default, this is a nicely formatted version of the porting phone number.
ステータス Status of this resource. It can hold one of the values: 1. Created, 2. Received, 3. Submitting, 4. Submitted, 5. Delivered, 6. Completed, 7. Canceled, 8. Rejected, 9. Failed. See section entitled Port Orders Status Values for more information on each of these statuses.
date_created The date that this resource was created, given as GMT RFC 2822 format.
date_updated The date that this resource was updated, given as GMT RFC 2822 format.
loa_sid Port LOA instance subresource SID, which is a 34 character string that uniquely identifies the electronic LOA document associated with this resource.
iso_country The ISO 3166-1 alpha-2 country code, e.g., “US”, in the service address associated with the porting phone number.
region Name of the region in the service address associated with the porting phone number. This can be a 2 letter state code in US, e.g., “CA”.
住所3(市区町村) Name of the city in the service address associated with the porting phone number.
postal_code Zip or postal code in the service address associated with the porting phone number.
street Name of the street in the service address associated with the porting phone number.
company_name Name of the company that owns the porting phone number. Please note that this is the name we will use to populate the “Business Name” field in the LOA associated with this resource.
first_name First name of the person who owns the porting phone number. Please note that this is the name we will use to populate the “First Name” field in the LOA associated with this resource, and that this person must be the one who is authorized to and will sign this LOA.
last_name Last name of the person who owns the porting phone number. Please note that this is the name we will use to populate the “Last Name” field in the LOA associated with this resource, and that this person must be the one who is authorized to and will sign the LOA.
Email Email address of the person who owns the porting phone number. Please note that this person must be the one who is authorized to and will sign the LOA.
ssn_last_four Last four digits of the social security number of the person who owns the porting phone number. Please note that this person must be the one who is authorized to and will sign the LOA. Also note that this field will not be returned as part of the API’s response to a GET request.
port_type Type of the porting phone number. This can be one of the values: 1. Landline, 2. Toll Free, 3. Wireless
activation_date Desired Firm Order Commitment (FOC) date and time, i.e., the date and time at which the number will port. Please note that this will be overridden if the earliest possible FOC date is on a later date. This must be in GMT RFC 2822 format.
billing_phone_number The main billing phone number on the account (with your current provider/carrier) that is associated with the porting phone number in this port request. This must be in E.164 format, e.g., +16175551212.
account_number Account number of the account (with the current provider/carrier) that is associated with the porting phone number. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers. Please note that this field will not be returned as part of the API’s response to a GET request.
pin_number PIN number of the account (with your current provider/carrier) that is associated with the porting phone number. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers. Please note that this field will not be returned as part of the API’s response to a GET request.
incoming_phone_number_sid Porting phone number SID, which is a 34 character string that uniquely identifies the porting phone number.
status_callback The URL that Twilio will POST to each time the port request status changes to one of Delivered, Failed, or Completed.
cc_emails Array of email address(es) of the person/people whom Twilio should notify each time the port request status changes to one of Delivered, Failed, or Completed.
reason_code Unique integer code that represents the reason for status change in this resource.
reason A human readable text that describes the reason for change in status of this resource.
url The URL for this resource.

Port Orders Status Values

Status 説明
Created Twilio has received the port request and is determining whether the phone number can be ported to Twilio.
Received Twilio has determined that the phone number in the port request can be ported to Twilio. Please note that the current provider/carrier of the phone number can still reject the port request later in the process based on other criteria.
Pending LOA for the port request has been generated, but the customer who requested the port has not signed the LOA yet.
Submitted LOA for the port request has been signed, and the phone number has been submitted to Twilio’s underlying provider/carrier to start the porting process.
Completed Porting process has completed, and the phone number is ready for use.
Canceled Port request was canceled by the user. At this point, it is no longer possible to re-submit the same port request.
Rejected Port request was rejected by the current provider/carrier of the phone number in this port request. At this point, it is no longer possible to re-submit the same port request.
失敗 Port request has failed. At this point, it is no longer possible to re-submit the same port request.

Port Order Related Errors

エラー コード Error Name Error Description
21801 Port Order: Missing Incoming Phone Number in E.164 format You didn’t specify a telephone number to port to Twilio.
21802 Port Order: Missing ISO 3166-1 alpha-2 Country Code of the Phone Number's Service Address with Current Provider You didn’t specify the country code in your porting telephone number’s Service Address as it appears in the Customer Service Record with your current telephone service provider.
21803 Port Order: Missing State or Region of the Phone Number's Service Address with Current Provider You didn’t specify the state or region in your porting telephone number’s Service Address as it appears in the Customer Service Record with your current telephone service provider.
21804 番号移管オーダー: 移管前のプロバイダーで電話番号のサービス・アドレスの都市が指定されていません 移管する電話番号のサービス・アドレスの都市が、現在ご利用のサービス・プロバイダーでカスタマー・サービス・レコードのとおりに指定されていませんでした。
21805 Port Order: Missing Postal Code of the Phone Number's Service Address with Current Provider You didn’t specify the zip or postal Code in your porting telephone number’s Service Address as it appears in the Customer Service Record with your current telephone service provider.
21806 番号移管オーダー: 移管前のプロバイダーで電話番号のサービス・アドレスの番地が指定されていません 移管する電話番号のサービス・アドレスの番地が、現在ご利用のサービス・プロバイダーでカスタマー・サービス・レコードのとおりに指定されていませんでした。
21807 Port Order: Missing First Name of Authorized Signatory You didn’t specify the first name of the person who owns the porting telephone phone number and is authorized to sign the associated Letter of Authorization.
21808 番号移管オーダー: 認証された署名者の氏(苗字)が見つかりません You didn’t specify the last name of the person who owns the porting telephone phone number and is authorized to sign the associated Letter of Authorization.
21809 Port Order: Missing Account Number (for Wireless Numbers only) You didn’t specify the account number associated with the porting telephone phone number. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers.
21810 Port Order: Missing PIN Number (for Wireless Numbers only) You didn’t specify the PIN associated with the porting telephone phone number. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers.
21811 Port Order: Missing Email Address of Authorized Signatory (for signing of LOA) You didn’t specify the email address associated with the porting telephone phone number.
21812 Port Order: Invalid Incoming Phone Number (must be in E.164 format) The porting telephone number you provided is not valid. This must be in E.164 format, e.g., “+16175551212”.
21813 Port Order: Invalid Country Code (must be in ISO 3166-1 alpha-2 format) The country code in your porting telephone number’s Service Address is not valid. This must be in ISO 3166-1 alpha-2 format, e.g., “US”.
21814 Port Order: Invalid Activation Date (must be in ISO 8601 format) The desired activation or Firm Order Commitment (FOC) date and time, i.e., the date and time at which the number will port, you provided is not valid. This must be in GMT RFC 2822 format.
21815 Port Order: Invalid Billing Phone Number (must be in E.164 format) The billing telephone number you provided is not valid.
21816 Port Order: Invalid PIN Number The PIN number you provided is not valid.
21817 Port Order: Invalid Last Four digits of Social Security Number The last 4 digits of the social security number you provided is not valid.
21818 Port Order: Invalid Email Address The email address you provided is not valid.
21819 Port Order: Invalid Callback URL The callback URL you provided is not valid.
21820 Port Order: Invalid Email Address(es) in CC List (must be an array of valid Email Addresses) One or more of the email address(es) you provided is/are not valid.
21822 Port Order: Invalid Status The status you provided is not valid. See section entitled Port Orders Status Values for more information on each of these statuses.
21824 番号移管オーダー: 社会保障番号の最後の4桁が指定されていません 移管する電話番号の持ち主で、関連する承諾書に署名する認証を持つ人物の社会保障番号の最後の4桁が指定されませんでした。 これは携帯電話番号には必須ですが、固定電話またはフリーダイヤルの場合はオプションです。
21825 Port Order: Invalid Before SID The SID you provided is not valid.
21826 Port Order: Invalid After SID The SID you provided is not valid.
21827 番号移管オーダー: 着信用電話番号は移管できません The telephone number is not portable. This might be because the number already exists in Twilio, or because the number can’t be supported by Twilio.
21828 Port Order: Invalid Name of Authorized Signatory The first name and/or last name of the person, who owns the porting telephone number and is authorized to and will sign the associated Letter of Authorization, you provided is not valid.
21829 Port Order: Port Order cannot be Changed This port request can no longer be modified. Port Orders instance resources can be modified so long as they are in either “Created” or “Received” status.
21830 Port Order: Port Order cannot be Canceled This port request can no longer be canceled. Port requests cannot be canceled once they reach the “Completed” status.
21831 Port Order: Port is not Possible This port request has been rejected by your current telephone service provider. Please refer to Why was my port request rejected? for more information.
21832 Port Order: Port Orders with Wireless Phone Numbers cannot be Cancelled after LOA is signed This port request can no longer be canceled. Wireless port requests can be canceled so long as they are in one of “Created”, “Received”, or “Submitting” status.
21833 Port Order: Port Order cannot be Canceled since FOC date and time is in less than 48 hours This port request can no longer be canceled since the FOC date and time, i.e., the date and time at which the number will port, is in less than 48 hours.
21834 Port Order: Invalid Address: The given Street of the Phone Number's Service Address does not match the given City, State, and/or Postal Code The street name you provided does not exist in the City, State, and/or Postal Code you provided in the Port Order.
21835 Port Order: Port Order cannot be Completed Your port order cannot be completed. This is because either Twilio's underlying carrier isn't set up to support the porting phone number or your current carrier has rejected the port request.
21836 Port Order: Missing Account Number (for Wireless Numbers only) and Missing Last Four digits of Social Security Number (for Wireless Numbers only) You didn’t specify the account number associated with and the last four digits of social security number of the person who owns the porting telephone phone number. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers.
21837 Port Order: Incoming Phone Number is already in the porting process with an existing Port Order The porting phone number is part of a Letter of Authorization that has already been signed.
21838 Port Order: Incoming Phone Number is already in Twilio Inventory. Please contact Support The porting phone number is already in Twilio Inventory and cannot be ported. Please contact Support.

HTTP GET

Returns a single, existing Port Orders instance resource specified by the requested Port Orders instance resource SID, or {PortOrderSid}

リクエスト
$ curl -G https://preview.twilio.com/porting/PortOrders/PO800f449d0399ed014aae2bcc0cc2f2ec \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
レスポンス
{
    "sid": "PO800f449d0399ed014aae2bcc0cc2f2ec",
    "number": "+14153077754",
    "friendly_name": "PortNumber1",
    "status": "Received",
    "date_created": "Mon, 16 Aug 2016 03:45:01 +0000",
    "date_updated": "Wed, 18 Aug 2016 03:45:01 +0000",
    "loa_sid": "PX800f449d0399ed014aae2bcc0cc2f2ec",
    "iso_country": "US",
    "region": "CA",
    "city": "San Francisco",
    "postal_code": "94107",
    "street": "645 Random St",
    "company_name": "Random Inc",
    "first_name": "Jim",
    "last_name": "Smith",
    "email": "jim.smith@random.com",
    "ssn_last_four": "1234",
    "port_type": "Landline",
    "activation_date": "Mon, 16 Aug 2016 03:45:01 +0000",
    "billing_phone_number": "None",
    "account_number": "7754",
    "pin_number": "5680",
    "incoming_phone_number_sid": "PN00f449d0399ed014aae2bcc0cc245lf",
    "status_callback": "http://portingworld.com/porting",
    "reason_code": "2346",
    "reason": "",
    "cc_emails": ["blah@twilio.com", "porting@twilio.com"],
    "url": "https://preview.twilio.com/porting/PortOrders/PO800f449d0399ed014aae2bcc0cc2f2ec"
}

HTTP POST/PUT

Tries to update a single, existing Port Orders instance resource’s properties and returns the updated resource representation if successful. The returned response is identical to that returned when making a GET request. Please note that the existing Port Orders instance resource’s properties that hold the service address values and FOC dates can be updated only when the resource is in either “Created” or “Received” status.

HTTP DELETE

Cancels the port request (consequently, also cancels the porting of the phone number in this port request) and sets the status on this Port Orders instance resource to “Cancelled”. The returned response is identical to that returned above when making a GET request.

Port LOAs Instance Resource

The “Port LOAs” instance resource represents a single electronic Letter of Authorization (LOA) document that authorizes Twilio to port one or more phone numbers to Twilio on behalf of the customer requesting the port. This instance resource is automatically created using the information that was submitted to Twilio when creating the corresponding Port Orders instance resource.

リソース URI

preview.twilio.com/porting/Loas/{PortLOASid}

リソースのプロパティ

プロパティ 説明
sid このリソースを一意に識別する 34 文字の文字列です。
ステータス Status of this resource. It can hold one of the values: 1. open, 2. signing, 3. signed, or 4. canceled
uri The URI for this resource, relative to https://preview.twilio.com

Port LOA Related Errors

エラー コード Error Name Error Description
21901 Port Order LOA: Invalid SID The SID you provided is not valid.
21904 Port Order LOA: Invalid Status The status you provided is not valid.
21905 Port Order LOA: Signature Request has already been sent The LOA has already been signed.

HTTP GET

Returns a single, existing Port LOA instance resource specified by the requested Port LOA instance resource SID, or {PortLOASid}.

リクエスト
$ curl -G https://preview.twilio.com/porting/Loas/PX800f449d0399ed014aae2bcc0cc2f2ec \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
レスポンス
{
    "status": "signing",
    "first_name": "Jim",
    "last_name": "Smith",
    "sid": "PX800f449d0399ed014aae2bcc0cc2f2ec",
    "email": "jim.smith@random.com"
}

HTTP POST/PUT

Issuing POST or PUT to this resource with its “status” property set to “signing” will update a single, existing Port LOAs instance resource associated with one or more port requests and initiate the LOA signing process. This will send an email to the email address that was provided with associated port requests. Please note that a single Port LOAs instance resource is associated with multiple Port Orders instance resource(s) that share the same name, address, type of port, and Twilio account.

リクエスト
$ curl -XPOST https://preview.twilio.com/porting/Loas/PX800f449d0399ed014aae2bcc0cc2f2ec \ 
    -H "Content-Type: application/json" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token' \
    -d '{"status":"signing"}'
レスポンス

The returned response is identical to that returned above when making a GET request.

HTTP PUT

Not available

HTTP DELETE

Not available

Port Orders List Resource

The Port Orders list resource represents the list of all phone numbers that are associated with a Twilio account or subaccount, identified by an Account SID, and are in the process of porting to Twilio.

リソース URI

preview.twilio.com/porting/PortOrders

リスト フィルター

You may limit the list by providing certain query string parameters to the listing resource. Note that the parameters are case-sensitive.

PARAMETER 説明
ステータス Only retrieve the list of port orders in this state. Possible values: 1. Created, 2. Received, 3. Submitting, 4. Submitted, 5. Delivered, 6. Completed, 7. Canceled, 8. Rejected, 9. Failed
activation_date Only retrieve the list of port orders comprising phone numbers that are scheduled to become active on a particular date, in GMT RFC 2822 format, e.g., activation_date=2009-07-06. Inequality can also be specified to retrieve the list of port orders comprising phone numbers that are scheduled to become active on or before midnight on a particular date, e.g. activation_date<=2009-07-06, or to retrieve the list of port orders comprising phone numbers that are scheduled to become active on or after midnight on a particular date, e.g. activation_date>=2009-07-06.
friendly_name Only retrieve the list of port orders with this friendly name.
date_created Only retrieve the list of port orders that were created on a particular date, in GMT RFC 2822 format, e.g., date_created=2009-07-06. Inequality can be specified to retrieve the list of port orders that were created before or after a particular date as well.
番号 Only retrieve the list of port orders that comprise this porting phone number. This must be in E.164 format, e.g., +16175551212.
before_sid Only retrieve port orders before the port order with this SID in the list of all port orders.
after_sid Only retrieve port orders after the port order with this SID in the list of all port orders.

HTTP GET

Returns the list of all port orders that have the friendly name, “Random123”.

リクエスト
$ curl -G https://preview.twilio.com/porting/PortOrders \ 
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token' \
    -d "FriendlyName=Random123" \
レスポンス
{
    "page": 0,
    "page_size": 50,
    "uri": "/porting/PortOrders.json",
    "first_page_uri": "/porting/PortOrders.json?Page=0&PageSize=50",
    "next_page_uri": "/porting/PortOrders.json?Page=1&PageSize=50",
    "previous_page_uri": null,
    "port_numbers": [{
        "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "api_version": "porting",
        "sid": "PO800f449d0399ed014aae2bcc0cc2f2ec",
        "number": "+14153077754",
        "friendly_name": "Random123",
        "status": "Received",
        "date_created": "Mon, 16 Aug 2016 03:45:01 +0000",
        "date_updated": "Wed, 18 Aug 2016 03:45:01 +0000",
        "loa_sid": "PX800f449d0399ed014aae2bcc0cc2f2ec",
        "iso_country": "US",
        "region": "CA",
        "city": "San Francisco",
        "postal_code": "94107",
        "street": "645 Random St",
        "company_name": "Random Inc",
        "first_name": "Jim",
        "last_name": "Smith",
        "email": "jim.smith@random.com",
        "ssn_last_four": "1234",
        "port_type": "Landline",
        "activation_date": "Mon, 16 Aug 2016 03:45:01 +0000",
        "billing_phone_number": "None",
        "account_number": "7754",
        "pin_number": "5680",
        "incoming_phone_number_sid": "PN00f449d0399ed014aae2bcc0cc245lf",
        "status_callback": "http://portingworld.com/porting",
        "emails": ["blah@twilio.com", "porting@twilio.com"],
        "reason_code": "2346",
        "reason": "",
        "uri": "/porting/PortOrders/PY800f449d0399ed014aae2bcc0cc2f2ec.json",
        "before_sid": "PO800f449d0399ed014aae2bcc0cc234gh",
        "after_sid": "PO800f449d0399ed014aae2bcc0cc278sd"
    },...]
}

HTTP POST

Initiates a single, new port request by creating a single, new Port Orders instance resource comprising the phone number to be ported to Twilio.

必要なパラメーター

PARAMETER 説明
番号 Porting phone number in E.164 format, e.g., +16175551212.
iso_country The ISO 3166-1 alpha-2 country code in the service address associated with the porting phone number, e.g., US.
region Name of the region in the service address associated with the porting phone number. This can be a 2 letter state code in US, e.g., CA.
住所3(市区町村) Name of the city in the service address associated with the porting phone number.
postal_code Zip code or postal code in the service address associated with the porting phone number.
street Name of the street in the service address associated with the porting phone number.
first_name First name of the person that owns the porting phone number. Please note that this is the name we will use to populate the “First Name” field in the LOA associated with this port request, and that this person must be the one who is authorized to and will sign the LOA.
last_name Last name of the person that owns the porting phone number. Please note that this is the name we will use to populate the “Last Name” field in the LOA associated with this port request, and that this person must be the one who is authorized to and will sign the LOA.
Email Email address of the person that owns the porting phone number. Please note that this person must be the one who is authorized to and will sign the LOA.

オプションパラメーター

PARAMETER 説明
friendly_name A human readable descriptive text for this resource, up to 64 characters long. By default, this is a nicely formatted version of the phone number.
company_name Name of the company that owns the porting phone number. Please note that this is the name we will use to populate the “Business Name” field in the LOA associated with this port request.
billing_phone_number The main billing phone number on the account (with your current provider/carrier) that is associated with the porting phone number in this port request. This must be in E.164 format, e.g., +16175551212.
account_number Account number of the account (with your current provider/carrier) that is associated with the porting phone number in this port request. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers.
pin_number PIN number of the account (with your current provider/carrier) that is associated with the porting phone number in this port request. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers.
ssn_last_four Last four digits of the social security number of the person that owns the porting phone number. Please note that this person must be the one who is authorized to and will sign the LOA. This is mandatory for Wireless numbers but optional for Landline and Toll Free numbers.
activation_date Desired Firm Order Commitment (FOC) date and time, given as GMT RFC 2822 format – i.e., the date and time at which the number will port. This will be overridden if the earliest possible FOC date is on a later date.
status_callback The URL that Twilio will POST to each time the port request status changes to one of Delivered, Failed, or Completed.
cc_emails Array of email address(es) of the person/people whom Twilio should notify each time the port request status changes to one of Delivered, Failed, or Completed.
リクエスト
$ curl -XPOST https://preview.twilio.com/porting/PortOrders \
    -H "Content-Type: application/json" \
    -d '{"number":"+14153077754","iso_country":"US","region":"CA","city":"SAN FRANCISCO","postal_code":94107,"street":"645 Harrison st.","first_name":"James","last_name":"The Third","email":"james.thethird@random.com"}'  \
    -u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"
レスポンス

The returned response is identical to that returned on issuing a GET request to Port Orders instance resource.

HTTP PUT

Not available

HTTP DELETE

Not available