Number Porting

Number Porting operations

Verify phone number portability

Verifies the portability of a list of phone numbers.

Example request body

{
  "phone_numbers": [
    {
      "phone_number": "+13125354200"
    },
    {
      "phone_number": "+13125354500"
    }
  ]
}
Request
Request Body schema: application/json
required

List of phone numbers to check portability on

required
Array of objects (PhoneNumber)

List of phone numbers to check phone numbers

Array
phone_number
required
string

E164 formatted phone number

Responses
201

Portability check response

Response Schema: application/json
Array
required
Array of objects (PortabilityCheckResult)

List of phone numbers to check phone numbers on

Array
raw_number
required
string

The phone number as it was submitted

e164_number
string

The phone number parsed into e164 format

portable
required
boolean

Is the number portable?

portability_status
string

Specifies whether Telnyx was able to confirm portability for the rate center for this number

Enum: "pending" "confirmed" "provisional"
carrier_name
string

The underlying carrier associated with the phone number

coverage_category
required
string

Category of phone number. 'nanp_toll_free' indicates a toll free number on the North American Numbering Plan (NANP). 'nanp_generic' indicates a non toll-free NANP phone number. 'international' indicates a non-NANP phone number.

Enum: "nanp_generic" "nanp_toll_free" "international" "invalid"
non_portable_reason
string

Reason the phone number is not portable

Enum: "invalid_phone_number" "lrn_data_not_found" "no_coverage" "already_being_ported" "telnyx_number"
401

Unauthorized

422

Unprocessable entity. Check message field in response for details.

post/origination/porting/portability_checks
Request samples
application/json
{
  • "phone_numbers": [
    • {
      • "phone_number": "string"
      }
    ]
}
Response samples
application/json
[
  • {
    • "phone_numbers": [
      • {
        • "raw_number": "string",
        • "e164_number": "string",
        • "portable": true,
        • "portability_status": "pending",
        • "carrier_name": "string",
        • "coverage_category": "nanp_generic",
        • "non_portable_reason": "invalid_phone_number"
        }
      ]
    }
]

List all port exception types

Returns a list of port exception types.

Responses
200

Port Exception Type Response

Response Schema: application/json
Array
code
required
string

Porting exception code

description
required
string

Human readable description of porting exception type

get/origination/porting/porting_exception_types
Request samples 
Response samples 
application/json
[
  • {
    • "code": "string",
    • "description": "string"
    }
]
List all port requests
Returns a list of your port requests.


Request 
query Parameters
page
integer
 Default:  1
Page number of results to load


 
per_page
integer
 Default:  20
Number of results per page


 
search
string
Filter results by support_key (pr_*) or partial phone number


 
status
string
Filter results by status


 Enum: "incomplete" "complete"  
include_phone_numbers
boolean
 Default:  true
Include phone number objects in the results


 
include_sub_requests
boolean
 Default:  false
Include sub request objects in the results


 
Responses 
200
Port Requests Response


 Response Headers 
Total
integer
Total number of results


 
Total-Pages
integer
Total number of pages


 
Response Schema: application/json
 Array 
id
required
string
 
Array of objects (PortRequestPhoneNumber) 
Phone numbers associated with this port request


 
support_key
required
string
Key to reference when contacting Telnyx support


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
string
ISO 8601 formatted date indicating when the resource was updated.


 
required
Array of objects (PhoneNumberCountAndStatus) 
 
Array of objects (SubRequest) 
 
401
Unauthorized


get/origination/porting/port_requests
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "phone_numbers": [
      • {
        • "phone_number": "string",
        • "svtype": "string",
        • "carrier_name": "string",
        • "coverage_category": "nanp_generic",
        • "sub_request_id": "string",
        • "sub_request_status": "string",
        • "portability_status": "pending"
        }
      ],
    • "support_key": "string",
    • "created_at": "string",
    • "updated_at": "string",
    • "phone_number_counts_by_status": [
      • {
        • "status": "unassigned",
        • "count": 0
        }
      ],
    • "sub_requests": [
      • {
        • "id": "string",
        • "phone_numbers": [
          • {
            • "phone_number": "string",
            • "svtype": "string",
            • "carrier_name": "string",
            • "coverage_category": "nanp_generic",
            • "sub_request_id": "string",
            • "sub_request_status": "string",
            • "portability_status": "pending"
            }
          ],
        • "foc_date": "string",
        • "status": "unassigned",
        • "support_key": "string",
        • "phone_number_count": 0,
        • "underlying_carrier_names": [
          • "string"
          ],
        • "foc_date_requested_by_user": "string",
        • "person_or_company_name": "string",
        • "auth_person_name": "string",
        • "billing_phone_number": "string",
        • "street_address": "string",
        • "extended_address": "string",
        • "locality": "string",
        • "administrative_area": "string",
        • "postal_code": "string",
        • "country_code": "string",
        • "created_at": "string",
        • "updated_at": "string",
        • "default_connection_id": "string",
        • "default_message_profile_id": "string",
        • "porting_option": {
          • "type": "partial",
          • "remaining_numbers_action": "keep",
          • "new_billing_phone_number": "string"
          },
        • "pin_passcode": "string",
        • "account_number": "string",
        • "description": "string",
        • "tax_identifier": "string",
        • "business_identifier": "string",
        • "customer_rating": 0,
        • "customer_rating_comment": "string"
        }
      ]
    }
]
Retrieve a port request
Retrieves the details of an existing port request.


Request 
path Parameters
id
required
string
Port Request id


 
query Parameters
include_phone_numbers
boolean
 Default:  true
Include phone number objects in the results


 
include_sub_requests
boolean
 Default:  false
Include sub request objects in the results


 
Responses 
200
Port Request Response


Response Schema: application/json
id
required
string
 
Array of objects (PortRequestPhoneNumber) 
Phone numbers associated with this port request


 
support_key
required
string
Key to reference when contacting Telnyx support


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
string
ISO 8601 formatted date indicating when the resource was updated.


 
required
Array of objects (PhoneNumberCountAndStatus) 
 
Array of objects (SubRequest) 
 
401
Unauthorized


404
Resource not found


422
Unprocessable entity. Check message field in response for details.


get/origination/porting/port_requests/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "phone_numbers": [
    • {
      • "phone_number": "string",
      • "svtype": "string",
      • "carrier_name": "string",
      • "coverage_category": "nanp_generic",
      • "sub_request_id": "string",
      • "sub_request_status": "string",
      • "portability_status": "pending"
      }
    ],
  • "support_key": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "phone_number_counts_by_status": [
    • {
      • "status": "unassigned",
      • "count": 0
      }
    ],
  • "sub_requests": [
    • {
      • "id": "string",
      • "phone_numbers": [
        • {
          • "phone_number": "string",
          • "svtype": "string",
          • "carrier_name": "string",
          • "coverage_category": "nanp_generic",
          • "sub_request_id": "string",
          • "sub_request_status": "string",
          • "portability_status": "pending"
          }
        ],
      • "foc_date": "string",
      • "status": "unassigned",
      • "support_key": "string",
      • "phone_number_count": 0,
      • "underlying_carrier_names": [
        • "string"
        ],
      • "foc_date_requested_by_user": "string",
      • "person_or_company_name": "string",
      • "auth_person_name": "string",
      • "billing_phone_number": "string",
      • "street_address": "string",
      • "extended_address": "string",
      • "locality": "string",
      • "administrative_area": "string",
      • "postal_code": "string",
      • "country_code": "string",
      • "created_at": "string",
      • "updated_at": "string",
      • "default_connection_id": "string",
      • "default_message_profile_id": "string",
      • "porting_option": {
        • "type": "partial",
        • "remaining_numbers_action": "keep",
        • "new_billing_phone_number": "string"
        },
      • "pin_passcode": "string",
      • "account_number": "string",
      • "description": "string",
      • "tax_identifier": "string",
      • "business_identifier": "string",
      • "customer_rating": 0,
      • "customer_rating_comment": "string"
      }
    ]
}
Retrieve all sub requests for a port request
Returns a list of sub requests for a port request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
Responses 
200
Sub Requests Response


Response Schema: application/json
 Array 
id
required
string
 
Array of objects (PortRequestPhoneNumber) 
Phone numbers associated with this port request


 
foc_date
required
string
ISO 8601 formatted Date/Time of the FOC date


 
status
required
string
Status of sub request


 Enum: "unassigned" "in-process" "submitted" "exception" "foc-date-confirmed" "ported" "cancelled" "cancel-pending"  
support_key
required
string
Key to reference when contacting Telnyx support


 
phone_number_count
required
integer
Number of phone numbers attached to this sub request


 
underlying_carrier_names
Array of strings
Names of underlying carriers for phone numbers on this sub request


 
foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
person_or_company_name
required
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
required
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
required
string
ISO 8601 formatted date indicating when the resource was updated.


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
default_message_profile_id
required
string
Identifies the messaging profile to set on the numbers when the port completes


 
required
object (PortingOption) 
 
pin_passcode
required
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
required
string
The authorized person's account number with the current service provider


 
description
required
string
Description of draft sub request


 
tax_identifier
required
string
European tax identification number. Applicable only in the European Union


 
business_identifier
required
string
European business identification number. Applicable only in the European Union


 
customer_rating
integer
Once a sub request is ported, cancellation is requested or the sub request is cancelled, the user may rate their experience


 
customer_rating_comment
string
A comment related to the customer rating.


 
401
Unauthorized


get/origination/porting/port_requests/{port_request_id}/sub_requests
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "phone_numbers": [
      • {
        • "phone_number": "string",
        • "svtype": "string",
        • "carrier_name": "string",
        • "coverage_category": "nanp_generic",
        • "sub_request_id": "string",
        • "sub_request_status": "string",
        • "portability_status": "pending"
        }
      ],
    • "foc_date": "string",
    • "status": "unassigned",
    • "support_key": "string",
    • "phone_number_count": 0,
    • "underlying_carrier_names": [
      • "string"
      ],
    • "foc_date_requested_by_user": "string",
    • "person_or_company_name": "string",
    • "auth_person_name": "string",
    • "billing_phone_number": "string",
    • "street_address": "string",
    • "extended_address": "string",
    • "locality": "string",
    • "administrative_area": "string",
    • "postal_code": "string",
    • "country_code": "string",
    • "created_at": "string",
    • "updated_at": "string",
    • "default_connection_id": "string",
    • "default_message_profile_id": "string",
    • "porting_option": {
      • "type": "partial",
      • "remaining_numbers_action": "keep",
      • "new_billing_phone_number": "string"
      },
    • "pin_passcode": "string",
    • "account_number": "string",
    • "description": "string",
    • "tax_identifier": "string",
    • "business_identifier": "string",
    • "customer_rating": 0,
    • "customer_rating_comment": "string"
    }
]
Retrieve a sub request
Retrieves the details of an existing sub request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
id
required
string
Sub Request id


 
Responses 
200
Sub Requests Response


Response Schema: application/json
 Array 
id
required
string
 
Array of objects (PortRequestPhoneNumber) 
Phone numbers associated with this port request


 
foc_date
required
string
ISO 8601 formatted Date/Time of the FOC date


 
status
required
string
Status of sub request


 Enum: "unassigned" "in-process" "submitted" "exception" "foc-date-confirmed" "ported" "cancelled" "cancel-pending"  
support_key
required
string
Key to reference when contacting Telnyx support


 
phone_number_count
required
integer
Number of phone numbers attached to this sub request


 
underlying_carrier_names
Array of strings
Names of underlying carriers for phone numbers on this sub request


 
foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
person_or_company_name
required
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
required
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
required
string
ISO 8601 formatted date indicating when the resource was updated.


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
default_message_profile_id
required
string
Identifies the messaging profile to set on the numbers when the port completes


 
required
object (PortingOption) 
 
pin_passcode
required
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
required
string
The authorized person's account number with the current service provider


 
description
required
string
Description of draft sub request


 
tax_identifier
required
string
European tax identification number. Applicable only in the European Union


 
business_identifier
required
string
European business identification number. Applicable only in the European Union


 
customer_rating
integer
Once a sub request is ported, cancellation is requested or the sub request is cancelled, the user may rate their experience


 
customer_rating_comment
string
A comment related to the customer rating.


 
401
Unauthorized


get/origination/porting/port_requests/{port_request_id}/sub_requests/{id}
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "phone_numbers": [
      • {
        • "phone_number": "string",
        • "svtype": "string",
        • "carrier_name": "string",
        • "coverage_category": "nanp_generic",
        • "sub_request_id": "string",
        • "sub_request_status": "string",
        • "portability_status": "pending"
        }
      ],
    • "foc_date": "string",
    • "status": "unassigned",
    • "support_key": "string",
    • "phone_number_count": 0,
    • "underlying_carrier_names": [
      • "string"
      ],
    • "foc_date_requested_by_user": "string",
    • "person_or_company_name": "string",
    • "auth_person_name": "string",
    • "billing_phone_number": "string",
    • "street_address": "string",
    • "extended_address": "string",
    • "locality": "string",
    • "administrative_area": "string",
    • "postal_code": "string",
    • "country_code": "string",
    • "created_at": "string",
    • "updated_at": "string",
    • "default_connection_id": "string",
    • "default_message_profile_id": "string",
    • "porting_option": {
      • "type": "partial",
      • "remaining_numbers_action": "keep",
      • "new_billing_phone_number": "string"
      },
    • "pin_passcode": "string",
    • "account_number": "string",
    • "description": "string",
    • "tax_identifier": "string",
    • "business_identifier": "string",
    • "customer_rating": 0,
    • "customer_rating_comment": "string"
    }
]
Edit a sub request
Edits the details of an existing sub request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
id
required
string
Sub Request id


 
Request Body schema: application/json
required
Updated sub request details


foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
person_or_company_name
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
object (PortingOptionRequest) 
 
pin_passcode
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
string
The authorized person's account number with the current service provider


 
tax_identifier
string
European tax identification number. Applicable only in the European Union


 
business_identifier
string
European business identification number. Applicable only in the European Union


 
customer_rating
integer
Once a sub request is ported, cancellation is requested or the sub request is cancelled, the user may rate their experience.


 
customer_rating_comment
string
A comment related to the customer rating


 
Responses 
200
Sub Requests Response


Response Schema: application/json
 Array 
id
required
string
 
Array of objects (PortRequestPhoneNumber) 
Phone numbers associated with this port request


 
foc_date
required
string
ISO 8601 formatted Date/Time of the FOC date


 
status
required
string
Status of sub request


 Enum: "unassigned" "in-process" "submitted" "exception" "foc-date-confirmed" "ported" "cancelled" "cancel-pending"  
support_key
required
string
Key to reference when contacting Telnyx support


 
phone_number_count
required
integer
Number of phone numbers attached to this sub request


 
underlying_carrier_names
Array of strings
Names of underlying carriers for phone numbers on this sub request


 
foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
person_or_company_name
required
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
required
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
required
string
ISO 8601 formatted date indicating when the resource was updated.


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
default_message_profile_id
required
string
Identifies the messaging profile to set on the numbers when the port completes


 
required
object (PortingOption) 
 
pin_passcode
required
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
required
string
The authorized person's account number with the current service provider


 
description
required
string
Description of draft sub request


 
tax_identifier
required
string
European tax identification number. Applicable only in the European Union


 
business_identifier
required
string
European business identification number. Applicable only in the European Union


 
customer_rating
integer
Once a sub request is ported, cancellation is requested or the sub request is cancelled, the user may rate their experience


 
customer_rating_comment
string
A comment related to the customer rating.


 
401
Unauthorized


put/origination/porting/port_requests/{port_request_id}/sub_requests/{id}
Request samples 
application/json
{
  • "foc_date_requested_by_user": "string",
  • "person_or_company_name": "string",
  • "auth_person_name": "string",
  • "billing_phone_number": "string",
  • "street_address": "string",
  • "extended_address": "string",
  • "locality": "string",
  • "administrative_area": "string",
  • "postal_code": "string",
  • "country_code": "string",
  • "default_connection_id": "string",
  • "porting_option": {
    • "type": "partial",
    • "remaining_numbers_action": "keep",
    • "new_billing_phone_number": "string"
    },
  • "pin_passcode": "string",
  • "account_number": "string",
  • "tax_identifier": "string",
  • "business_identifier": "string",
  • "customer_rating": 0,
  • "customer_rating_comment": "string"
}
Response samples 
application/json
[
  • {
    • "id": "string",
    • "phone_numbers": [
      • {
        • "phone_number": "string",
        • "svtype": "string",
        • "carrier_name": "string",
        • "coverage_category": "nanp_generic",
        • "sub_request_id": "string",
        • "sub_request_status": "string",
        • "portability_status": "pending"
        }
      ],
    • "foc_date": "string",
    • "status": "unassigned",
    • "support_key": "string",
    • "phone_number_count": 0,
    • "underlying_carrier_names": [
      • "string"
      ],
    • "foc_date_requested_by_user": "string",
    • "person_or_company_name": "string",
    • "auth_person_name": "string",
    • "billing_phone_number": "string",
    • "street_address": "string",
    • "extended_address": "string",
    • "locality": "string",
    • "administrative_area": "string",
    • "postal_code": "string",
    • "country_code": "string",
    • "created_at": "string",
    • "updated_at": "string",
    • "default_connection_id": "string",
    • "default_message_profile_id": "string",
    • "porting_option": {
      • "type": "partial",
      • "remaining_numbers_action": "keep",
      • "new_billing_phone_number": "string"
      },
    • "pin_passcode": "string",
    • "account_number": "string",
    • "description": "string",
    • "tax_identifier": "string",
    • "business_identifier": "string",
    • "customer_rating": 0,
    • "customer_rating_comment": "string"
    }
]
List allowed FOC dates
Returns a list of allowed FOC dates for a sub request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
id
required
string
Sub Request id


 
Responses 
200
Allowed FOC dates


Response Schema: application/json
 Array 
start
required
string
ISO 8601 formatted Date/Time of the start of the allowed foc date interval


 
end
required
string
ISO 8601 formatted Date/Time of the end of the allowed foc date interval


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


get/origination/porting/port_requests/{port_request_id}/sub_requests/{id}/allowed_foc_dates
Request samples 
Response samples 
application/json
[
  • {
    • "start": "string",
    • "end": "string"
    }
]
Request cancellation
Request the cancellation of a  sub request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
id
required
string
Sub Request id


 
Responses 
200
Sub Request Updated


Response Schema: application/json
id
required
string
 
Array of objects (PortRequestPhoneNumber) 
Phone numbers associated with this port request


 
foc_date
required
string
ISO 8601 formatted Date/Time of the FOC date


 
status
required
string
Status of sub request


 Enum: "unassigned" "in-process" "submitted" "exception" "foc-date-confirmed" "ported" "cancelled" "cancel-pending"  
support_key
required
string
Key to reference when contacting Telnyx support


 
phone_number_count
required
integer
Number of phone numbers attached to this sub request


 
underlying_carrier_names
Array of strings
Names of underlying carriers for phone numbers on this sub request


 
foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
person_or_company_name
required
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
required
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
required
string
ISO 8601 formatted date indicating when the resource was updated.


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
default_message_profile_id
required
string
Identifies the messaging profile to set on the numbers when the port completes


 
required
object (PortingOption) 
 
pin_passcode
required
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
required
string
The authorized person's account number with the current service provider


 
description
required
string
Description of draft sub request


 
tax_identifier
required
string
European tax identification number. Applicable only in the European Union


 
business_identifier
required
string
European business identification number. Applicable only in the European Union


 
customer_rating
integer
Once a sub request is ported, cancellation is requested or the sub request is cancelled, the user may rate their experience


 
customer_rating_comment
string
A comment related to the customer rating.


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


post/origination/porting/port_requests/{port_request_id}/sub_requests/{id}/cancellation
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "phone_numbers": [
    • {
      • "phone_number": "string",
      • "svtype": "string",
      • "carrier_name": "string",
      • "coverage_category": "nanp_generic",
      • "sub_request_id": "string",
      • "sub_request_status": "string",
      • "portability_status": "pending"
      }
    ],
  • "foc_date": "string",
  • "status": "unassigned",
  • "support_key": "string",
  • "phone_number_count": 0,
  • "underlying_carrier_names": [
    • "string"
    ],
  • "foc_date_requested_by_user": "string",
  • "person_or_company_name": "string",
  • "auth_person_name": "string",
  • "billing_phone_number": "string",
  • "street_address": "string",
  • "extended_address": "string",
  • "locality": "string",
  • "administrative_area": "string",
  • "postal_code": "string",
  • "country_code": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "default_connection_id": "string",
  • "default_message_profile_id": "string",
  • "porting_option": {
    • "type": "partial",
    • "remaining_numbers_action": "keep",
    • "new_billing_phone_number": "string"
    },
  • "pin_passcode": "string",
  • "account_number": "string",
  • "description": "string",
  • "tax_identifier": "string",
  • "business_identifier": "string",
  • "customer_rating": 0,
  • "customer_rating_comment": "string"
}
List exceptions
Returns a list of exceptions for a sub request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
id
required
string
Sub Request id


 
Responses 
200
Sub Request Exceptions


Response Schema: application/json
 Array 
id
required
string
 
code
required
string
Porting exception code


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


get/origination/porting/port_requests/{port_request_id}/sub_requests/{id}/exceptions
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "code": "string"
    }
]
List all comments for a port request
Returns a list of comments for a port request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
Responses 
200
Comments Response


Response Schema: application/json
 Array 
id
required
string
 
body
required
string
Body of comment


 
sub_request_id
string
 Default:  null
Id of associated sub request


 
user_id
string
Id of user who created the comment. Will be null if created by Telnyx Admin


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
401
Unauthorized


get/origination/porting/port_requests/{port_request_id}/comments
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "body": "string",
    • "sub_request_id": null,
    • "user_id": "string",
    • "created_at": "string"
    }
]
Create a comment on a port request
Creates a comment on a port request.


Request 
path Parameters
port_request_id
required
string
Port Request id


 
Request Body schema: application/json
required
Comment to post on this port request


body
required
string
Body of comment


 
sub_request_id
string
 Default:  null
Id of associated sub request. Send null to post a comment on the overall port request


 
Responses 
201
Comment Response


Response Schema: application/json
id
required
string
 
body
required
string
Body of comment


 
sub_request_id
string
 Default:  null
Id of associated sub request


 
user_id
string
Id of user who created the comment. Will be null if created by Telnyx Admin


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


post/origination/porting/port_requests/{port_request_id}/comments
Request samples 
application/json
{
  • "body": "string",
  • "sub_request_id": null
}
Response samples 
application/json
{
  • "id": "string",
  • "body": "string",
  • "sub_request_id": null,
  • "user_id": "string",
  • "created_at": "string"
}
List all supporting documents for a port request
Returns a list of supporting documents for a port request.


Request 
path Parameters
port_request_id
required
string
Port request id


 
Responses 
200
Supporting Document Responses


Response Schema: application/json
 Array 
id
required
string
 
body
required
string
Description of supporting document


 
document_type
required
string
Type of document


 Enum: "loa" "csr" "invoice" "other"  
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
401
Unauthorized


get/origination/porting/port_requests/{port_request_id}/supporting_documents
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "body": "string",
    • "document_type": "loa",
    • "created_at": "string"
    }
]
Retrieve a supporting document
Retrieves the details of an existing supporting document.


Request 
path Parameters
port_request_id
required
string
Port request id


 
id
required
string
Supporting document id


 
Responses 
200
Supporting Document Response


Response Schema: application/json
id
required
string
 
body
required
string
Description of supporting document


 
document_type
required
string
Type of document


 Enum: "loa" "csr" "invoice" "other"  
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
401
Unauthorized


get/origination/porting/port_requests/{port_request_id}/supporting_documents/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "body": "string",
  • "document_type": "loa",
  • "created_at": "string"
}
List all draft port requests
Returns a list of your draft port requests.


Request 
query Parameters
page
integer
 Default:  1
Page number of results to load


 
per_page
integer
 Default:  20
Number of results per page


 
search
string
Filter results by partial phone number


 
status
string
Filter results by status


 Enum: "pending" "submitted"  
include_phone_numbers
boolean
 Default:  true
Include phone number objects in the results


 
include_sub_requests
boolean
 Default:  false
Include sub request objects in the results


 
Responses 
200
Draft Port Requests Response


 Response Headers 
Total
integer
Total number of results


 
Total-Pages
integer
Total number of pages


 
Response Schema: application/json
 Array 
id
required
string
 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
status
required
string
Draft port request status


 Enum: "pending" "submitted"  
phone_number_count
required
integer
Count of phone numbers associated with this draft port request


 
Array of objects (DraftPortRequestPhoneNumber) 
Phone numbers associated with this draft port request


 
Array of objects (DraftSubRequest) 
 
port_request_id
required
string
ID the associated Port Request. This field is filled if the draft port request has been submitted.


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


get/origination/porting/draft_port_requests
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "created_at": "string",
    • "status": "pending",
    • "phone_number_count": 0,
    • "phone_numbers": [
      • {
        • "phone_number": "string",
        • "svtype": "string",
        • "carrier_name": "string",
        • "coverage_category": "nanp_generic",
        • "sub_request_id": "string",
        • "portability_status": "pending"
        }
      ],
    • "sub_requests": [
      • {
        • "id": "string",
        • "complete": true,
        • "phone_numbers": [
          • {
            • "phone_number": "string",
            • "svtype": "string",
            • "carrier_name": "string",
            • "coverage_category": "nanp_generic",
            • "sub_request_id": "string",
            • "portability_status": "pending"
            }
          ],
        • "foc_date_requested_by_user": "string",
        • "phone_number_count": 0,
        • "underlying_carrier_names": [
          • "string"
          ],
        • "person_or_company_name": "string",
        • "auth_person_name": "string",
        • "billing_phone_number": "string",
        • "street_address": "string",
        • "extended_address": "string",
        • "locality": "string",
        • "administrative_area": "string",
        • "postal_code": "string",
        • "country_code": "string",
        • "created_at": "string",
        • "default_connection_id": "string",
        • "default_message_profile_id": "string",
        • "porting_option": {
          • "type": "partial",
          • "remaining_numbers_action": "keep",
          • "new_billing_phone_number": "string"
          },
        • "pin_passcode": "string",
        • "account_number": "string",
        • "description": "string",
        • "tax_identifier": "string",
        • "business_identifier": "string"
        }
      ],
    • "port_request_id": "string"
    }
]
Create a draft port request
Creates a new draft port request object.


Request 
Request Body schema: application/json
required
Draft port request to create


required
Array of objects (PhoneNumber) 
List of phone numbers to port


 
 Array 
phone_number
required
string
E164 formatted phone number


 
Responses 
201
Draft port request response


Response Schema: application/json
id
required
string
 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
status
required
string
Draft port request status


 Enum: "pending" "submitted"  
phone_number_count
required
integer
Count of phone numbers associated with this draft port request


 
Array of objects (DraftPortRequestPhoneNumber) 
Phone numbers associated with this draft port request


 
Array of objects (DraftSubRequest) 
 
port_request_id
required
string
ID the associated Port Request. This field is filled if the draft port request has been submitted.


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


post/origination/porting/draft_port_requests
Request samples 
application/json
{
  • "phone_numbers": [
    • {
      • "phone_number": "string"
      }
    ]
}
Response samples 
application/json
{
  • "id": "string",
  • "created_at": "string",
  • "status": "pending",
  • "phone_number_count": 0,
  • "phone_numbers": [
    • {
      • "phone_number": "string",
      • "svtype": "string",
      • "carrier_name": "string",
      • "coverage_category": "nanp_generic",
      • "sub_request_id": "string",
      • "portability_status": "pending"
      }
    ],
  • "sub_requests": [
    • {
      • "id": "string",
      • "complete": true,
      • "phone_numbers": [
        • {
          • "phone_number": "string",
          • "svtype": "string",
          • "carrier_name": "string",
          • "coverage_category": "nanp_generic",
          • "sub_request_id": "string",
          • "portability_status": "pending"
          }
        ],
      • "foc_date_requested_by_user": "string",
      • "phone_number_count": 0,
      • "underlying_carrier_names": [
        • "string"
        ],
      • "person_or_company_name": "string",
      • "auth_person_name": "string",
      • "billing_phone_number": "string",
      • "street_address": "string",
      • "extended_address": "string",
      • "locality": "string",
      • "administrative_area": "string",
      • "postal_code": "string",
      • "country_code": "string",
      • "created_at": "string",
      • "default_connection_id": "string",
      • "default_message_profile_id": "string",
      • "porting_option": {
        • "type": "partial",
        • "remaining_numbers_action": "keep",
        • "new_billing_phone_number": "string"
        },
      • "pin_passcode": "string",
      • "account_number": "string",
      • "description": "string",
      • "tax_identifier": "string",
      • "business_identifier": "string"
      }
    ],
  • "port_request_id": "string"
}
Retrieve a draft port request
Retrieves the details of an existing draft port request.


Request 
path Parameters
id
required
string
Draft Port Request id


 
query Parameters
include_phone_numbers
boolean
 Default:  true
Include phone number objects in the results


 
include_sub_requests
boolean
 Default:  false
Include sub request objects in the results


 
Responses 
200
Draft Port Request Response


Response Schema: application/json
id
required
string
 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
status
required
string
Draft port request status


 Enum: "pending" "submitted"  
phone_number_count
required
integer
Count of phone numbers associated with this draft port request


 
Array of objects (DraftPortRequestPhoneNumber) 
Phone numbers associated with this draft port request


 
Array of objects (DraftSubRequest) 
 
port_request_id
required
string
ID the associated Port Request. This field is filled if the draft port request has been submitted.


 
401
Unauthorized


404
Resource not found


422
Unprocessable entity. Check message field in response for details.


get/origination/porting/draft_port_requests/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "created_at": "string",
  • "status": "pending",
  • "phone_number_count": 0,
  • "phone_numbers": [
    • {
      • "phone_number": "string",
      • "svtype": "string",
      • "carrier_name": "string",
      • "coverage_category": "nanp_generic",
      • "sub_request_id": "string",
      • "portability_status": "pending"
      }
    ],
  • "sub_requests": [
    • {
      • "id": "string",
      • "complete": true,
      • "phone_numbers": [
        • {
          • "phone_number": "string",
          • "svtype": "string",
          • "carrier_name": "string",
          • "coverage_category": "nanp_generic",
          • "sub_request_id": "string",
          • "portability_status": "pending"
          }
        ],
      • "foc_date_requested_by_user": "string",
      • "phone_number_count": 0,
      • "underlying_carrier_names": [
        • "string"
        ],
      • "person_or_company_name": "string",
      • "auth_person_name": "string",
      • "billing_phone_number": "string",
      • "street_address": "string",
      • "extended_address": "string",
      • "locality": "string",
      • "administrative_area": "string",
      • "postal_code": "string",
      • "country_code": "string",
      • "created_at": "string",
      • "default_connection_id": "string",
      • "default_message_profile_id": "string",
      • "porting_option": {
        • "type": "partial",
        • "remaining_numbers_action": "keep",
        • "new_billing_phone_number": "string"
        },
      • "pin_passcode": "string",
      • "account_number": "string",
      • "description": "string",
      • "tax_identifier": "string",
      • "business_identifier": "string"
      }
    ],
  • "port_request_id": "string"
}
Submit a draft port request
Submits a draft port request. Once all of the sub requests belonging to a draft port request are populated with required information the draft port request can be submitted, initiating the porting process. Once successfully submitted changes can no longer be made to the draft port request. This request does not require a request body.


Request 
path Parameters
id
required
string
Draft Port Request id


 
Responses 
201
Draft port request response


Response Schema: application/json
id
required
string
 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
status
required
string
Draft port request status


 Enum: "pending" "submitted"  
phone_number_count
required
integer
Count of phone numbers associated with this draft port request


 
Array of objects (DraftPortRequestPhoneNumber) 
Phone numbers associated with this draft port request


 
Array of objects (DraftSubRequest) 
 
port_request_id
required
string
ID the associated Port Request. This field is filled if the draft port request has been submitted.


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


post/origination/porting/draft_port_requests/{id}/submit
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "created_at": "string",
  • "status": "pending",
  • "phone_number_count": 0,
  • "phone_numbers": [
    • {
      • "phone_number": "string",
      • "svtype": "string",
      • "carrier_name": "string",
      • "coverage_category": "nanp_generic",
      • "sub_request_id": "string",
      • "portability_status": "pending"
      }
    ],
  • "sub_requests": [
    • {
      • "id": "string",
      • "complete": true,
      • "phone_numbers": [
        • {
          • "phone_number": "string",
          • "svtype": "string",
          • "carrier_name": "string",
          • "coverage_category": "nanp_generic",
          • "sub_request_id": "string",
          • "portability_status": "pending"
          }
        ],
      • "foc_date_requested_by_user": "string",
      • "phone_number_count": 0,
      • "underlying_carrier_names": [
        • "string"
        ],
      • "person_or_company_name": "string",
      • "auth_person_name": "string",
      • "billing_phone_number": "string",
      • "street_address": "string",
      • "extended_address": "string",
      • "locality": "string",
      • "administrative_area": "string",
      • "postal_code": "string",
      • "country_code": "string",
      • "created_at": "string",
      • "default_connection_id": "string",
      • "default_message_profile_id": "string",
      • "porting_option": {
        • "type": "partial",
        • "remaining_numbers_action": "keep",
        • "new_billing_phone_number": "string"
        },
      • "pin_passcode": "string",
      • "account_number": "string",
      • "description": "string",
      • "tax_identifier": "string",
      • "business_identifier": "string"
      }
    ],
  • "port_request_id": "string"
}
List all sub requests for a draft port request
Returns a list of sub requests for a draft port request.


Request 
path Parameters
draft_port_request_id
required
string
Draft Port Request id


 
Responses 
200
Sub requests


Response Schema: application/json
 Array 
id
required
string
 
complete
required
boolean
True if object contains all necessary information, otherwise false


 
Array of objects (DraftPortRequestPhoneNumber) 
Phone numbers associated with this sub request


 
foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
phone_number_count
required
integer
Number of phone numbers attached to this sub request


 
underlying_carrier_names
Array of strings
Names of underlying carriers for phone numbers on this sub request


 
person_or_company_name
required
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
required
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
default_message_profile_id
required
string
Identifies the messaging profile to set on the numbers when the port completes


 
required
object (PortingOption) 
 
pin_passcode
required
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
required
string
The authorized person's account number with the current service provider


 
description
required
string
Description of draft sub request


 
tax_identifier
required
string
European tax identification number. Applicable only in the European Union


 
business_identifier
required
string
European business identification number. Applicable only in the European Union


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


get/origination/porting/draft_port_requests/{draft_port_request_id}/sub_requests
Request samples 
Response samples 
application/json
[
  • {
    • "id": "string",
    • "complete": true,
    • "phone_numbers": [
      • {
        • "phone_number": "string",
        • "svtype": "string",
        • "carrier_name": "string",
        • "coverage_category": "nanp_generic",
        • "sub_request_id": "string",
        • "portability_status": "pending"
        }
      ],
    • "foc_date_requested_by_user": "string",
    • "phone_number_count": 0,
    • "underlying_carrier_names": [
      • "string"
      ],
    • "person_or_company_name": "string",
    • "auth_person_name": "string",
    • "billing_phone_number": "string",
    • "street_address": "string",
    • "extended_address": "string",
    • "locality": "string",
    • "administrative_area": "string",
    • "postal_code": "string",
    • "country_code": "string",
    • "created_at": "string",
    • "default_connection_id": "string",
    • "default_message_profile_id": "string",
    • "porting_option": {
      • "type": "partial",
      • "remaining_numbers_action": "keep",
      • "new_billing_phone_number": "string"
      },
    • "pin_passcode": "string",
    • "account_number": "string",
    • "description": "string",
    • "tax_identifier": "string",
    • "business_identifier": "string"
    }
]
Retrieve a draft sub request
Retrieves the details of an existing draft sub request.


Request 
path Parameters
draft_port_request_id
required
string
Draft Port Request id


 
id
required
string
Sub Request id


 
Responses 
200
Sub request


Response Schema: application/json
id
required
string
 
complete
required
boolean
True if object contains all necessary information, otherwise false


 
Array of objects (DraftPortRequestPhoneNumber) 
Phone numbers associated with this sub request


 
foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
phone_number_count
required
integer
Number of phone numbers attached to this sub request


 
underlying_carrier_names
Array of strings
Names of underlying carriers for phone numbers on this sub request


 
person_or_company_name
required
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
required
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
created_at
required
string
ISO 8601 formatted date indicating when the resource was created.


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
default_message_profile_id
required
string
Identifies the messaging profile to set on the numbers when the port completes


 
required
object (PortingOption) 
 
pin_passcode
required
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
required
string
The authorized person's account number with the current service provider


 
description
required
string
Description of draft sub request


 
tax_identifier
required
string
European tax identification number. Applicable only in the European Union


 
business_identifier
required
string
European business identification number. Applicable only in the European Union


 
401
Unauthorized


422
Unprocessable entity. Check message field in response for details.


get/origination/porting/draft_port_requests/{draft_port_request_id}/sub_requests/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "complete": true,
  • "phone_numbers": [
    • {
      • "phone_number": "string",
      • "svtype": "string",
      • "carrier_name": "string",
      • "coverage_category": "nanp_generic",
      • "sub_request_id": "string",
      • "portability_status": "pending"
      }
    ],
  • "foc_date_requested_by_user": "string",
  • "phone_number_count": 0,
  • "underlying_carrier_names": [
    • "string"
    ],
  • "person_or_company_name": "string",
  • "auth_person_name": "string",
  • "billing_phone_number": "string",
  • "street_address": "string",
  • "extended_address": "string",
  • "locality": "string",
  • "administrative_area": "string",
  • "postal_code": "string",
  • "country_code": "string",
  • "created_at": "string",
  • "default_connection_id": "string",
  • "default_message_profile_id": "string",
  • "porting_option": {
    • "type": "partial",
    • "remaining_numbers_action": "keep",
    • "new_billing_phone_number": "string"
    },
  • "pin_passcode": "string",
  • "account_number": "string",
  • "description": "string",
  • "tax_identifier": "string",
  • "business_identifier": "string"
}
Update a draft sub request
Updates the specified draft sub request with the values of the parameters passed. Any parameters not included in the request will be left unchanged.


Note: this is where you can set a default connection to pre-configure the numbers on a sub request. Connections can be created using the create connections endpoint


Request 
path Parameters
draft_port_request_id
required
string
Draft Port Request id


 
id
required
string
Sub Request id


 
Request Body schema: application/json
required
Updated sub request details


foc_date_requested_by_user
required
string
ISO 8601 formatted Date/Time requested for the FOC date


 
person_or_company_name
string
Person Name or Company name requesting the port


 
auth_person_name
required
string
Name of person authorizing the port request


 
billing_phone_number
required
string
Billing phone number associated with these phone numbers


 
street_address
required
string
First line of billing address


 
extended_address
string
Second line of billing address


 
locality
required
string
City of billing address


 
administrative_area
required
string
Two character state abbreviation of billing address


 
postal_code
required
string
Postal Code of billing address


 
country_code
required
string
ISO3166-1 alpha-2 country code of billing address


 
default_connection_id
required
string
Identifies the connection to set on the numbers when the port completes


 
default_message_profile_id
required
string
Identifies the messaging profile to set on the numbers when the port completes


 
object (PortingOptionRequest) 
 
pin_passcode
string
PIN/passcode for accounts that have wireless type numbers


 
account_number
string
The authorized person's account number with the current service provider


 
tax_identifier
string
European tax identification number. Applicable only in the European Union


 
business_identifier
string
European business identification number. Applicable only in the European Union


 
Responses 
200
Sub request


Response Schema: application/json
id
required
string
 
complete
required
boolean
True if object contains all necessary information, otherwise false


 
Array of objects (DraftPortRequestPhoneNumber) 
Phone numbers associated with this sub request


 
foc_date_requested_by_user