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
required
string

ISO 8601 formatted Date/Time requested for the FOC date