Telnyx Porting Out - JavaScript

Installation

bash

npm install telnyx

Setup

javascript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

All examples below assume

client

is already initialized as shown above.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

javascript

try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}

Common error codes:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

rate limited (retry with exponential backoff).

Important Notes

Pagination: List methods return an auto-paginating iterator. Use
```
for await (const item of result) { ... }
```
to iterate through all pages automatically.

List portout requests

Returns the portout requests according to filters

GET /portouts

javascript

// Automatically fetches more pages as needed.
for await (const portoutDetails of client.portouts.list()) {
  console.log(portoutDetails.id);
}

Returns:

already_ported

(boolean),

authorized_name

(string),

carrier_name

(string),

city

(string),

created_at

(string),

current_carrier

(string),

end_user_name

(string),

foc_date

(string),

host_messaging

(boolean),

id

(string),

inserted_at

(string),

lsr

(array[string]),

phone_numbers

(array[string]),

pon

(string),

reason

(string | null),

record_type

(string),

rejection_code

(integer),

requested_foc_date

(string),

service_address

(string),

spid

(string),

state

(string),

status

(enum: pending, authorized, ported, rejected, rejected-pending, canceled),

support_key

(string),

updated_at

(string),

user_id

(uuid),

vendor

(uuid),

zip

(string)

List all port-out events

Returns a list of all port-out events.

GET /portouts/events

javascript

// Automatically fetches more pages as needed.
for await (const eventListResponse of client.portouts.events.list()) {
  console.log(eventListResponse);
}

Returns:

available_notification_methods

(array[string]),

created_at

(date-time),

event_type

(enum: portout.status_changed, portout.foc_date_changed, portout.new_comment),

id

(uuid),

payload

(object),

payload_status

(enum: created, completed),

portout_id

(uuid),

record_type

(string),

updated_at

(date-time)

Show a port-out event

Show a specific port-out event.

GET /portouts/events/{id}

javascript

const event = await client.portouts.events.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(event.data);

Returns:

available_notification_methods

(array[string]),

created_at

(date-time),

event_type

(enum: portout.status_changed, portout.foc_date_changed, portout.new_comment),

id

(uuid),

payload

(object),

payload_status

(enum: created, completed),

portout_id

(uuid),

record_type

(string),

updated_at

(date-time)

Republish a port-out event

Republish a specific port-out event.

POST /portouts/events/{id}/republish

javascript

await client.portouts.events.republish('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

List eligible port-out rejection codes for a specific order

Given a port-out ID, list rejection codes that are eligible for that port-out

GET /portouts/rejections/{portout_id}

javascript

const response = await client.portouts.listRejectionCodes('329d6658-8f93-405d-862f-648776e8afd7');

console.log(response.data);

Returns:

code

(integer),

description

(string),

reason_required

(boolean)

List port-out related reports

List the reports generated about port-out operations.

GET /portouts/reports

javascript

// Automatically fetches more pages as needed.
for await (const portoutReport of client.portouts.reports.list()) {
  console.log(portoutReport.id);
}

Returns:

created_at

(date-time),

document_id

(uuid),

id

(uuid),

params

(object),

record_type

(string),

report_type

(enum: export_portouts_csv),

status

(enum: pending, completed),

updated_at

(date-time)

Create a port-out related report

Generate reports about port-out operations.

POST /portouts/reports

javascript

const report = await client.portouts.reports.create({
  params: { filters: {} },
  report_type: 'export_portouts_csv',
});

console.log(report.data);

Returns:

created_at

(date-time),

document_id

(uuid),

id

(uuid),

params

(object),

record_type

(string),

report_type

(enum: export_portouts_csv),

status

(enum: pending, completed),

updated_at

(date-time)

Retrieve a report

Retrieve a specific report generated.

GET /portouts/reports/{id}

javascript

const report = await client.portouts.reports.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(report.data);

Returns:

created_at

(date-time),

document_id

(uuid),

id

(uuid),

params

(object),

record_type

(string),

report_type

(enum: export_portouts_csv),

status

(enum: pending, completed),

updated_at

(date-time)

Get a portout request

Returns the portout request based on the ID provided

GET /portouts/{id}

javascript

const portout = await client.portouts.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(portout.data);

Returns:

already_ported

(boolean),

authorized_name

(string),

carrier_name

(string),

city

(string),

created_at

(string),

current_carrier

(string),

end_user_name

(string),

foc_date

(string),

host_messaging

(boolean),

id

(string),

inserted_at

(string),

lsr

(array[string]),

phone_numbers

(array[string]),

pon

(string),

reason

(string | null),

record_type

(string),

rejection_code

(integer),

requested_foc_date

(string),

service_address

(string),

spid

(string),

state

(string),

status

(enum: pending, authorized, ported, rejected, rejected-pending, canceled),

support_key

(string),

updated_at

(string),

user_id

(uuid),

vendor

(uuid),

zip

(string)

List all comments for a portout request

Returns a list of comments for a portout request.

GET /portouts/{id}/comments

javascript

const comments = await client.portouts.comments.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(comments.data);

Returns:

body

(string),

created_at

(string),

id

(string),

portout_id

(string),

record_type

(string),

user_id

(string)

Create a comment on a portout request

Creates a comment on a portout request.

POST /portouts/{id}/comments

Optional:

body

(string)

javascript

const comment = await client.portouts.comments.create('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(comment.data);

Returns:

body

(string),

created_at

(string),

id

(string),

portout_id

(string),

record_type

(string),

user_id

(string)

List supporting documents on a portout request

List every supporting documents for a portout request.

GET /portouts/{id}/supporting_documents

javascript

const supportingDocuments = await client.portouts.supportingDocuments.list(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(supportingDocuments.data);

Returns:

created_at

(string),

document_id

(uuid),

id

(uuid),

portout_id

(uuid),

record_type

(string),

type

(enum: loa, invoice),

updated_at

(string)

Create a list of supporting documents on a portout request

Creates a list of supporting documents on a portout request.

POST /portouts/{id}/supporting_documents

Optional:

documents

(array[object])

javascript

const supportingDocument = await client.portouts.supportingDocuments.create(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(supportingDocument.data);

Returns:

created_at

(string),

document_id

(uuid),

id

(uuid),

portout_id

(uuid),

record_type

(string),

type

(enum: loa, invoice),

updated_at

(string)

Update Status

Authorize or reject portout request

PATCH /portouts/{id}/{status}

— Required:

reason

Optional:

host_messaging

(boolean)

javascript

const response = await client.portouts.updateStatus('authorized', {
  id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  reason: 'I do not recognize this transaction',
});

console.log(response.data);

Returns:

already_ported

(boolean),

authorized_name

(string),

carrier_name

(string),

city

(string),

created_at

(string),

current_carrier

(string),

end_user_name

(string),

foc_date

(string),

host_messaging

(boolean),

id

(string),

inserted_at

(string),

lsr

(array[string]),

phone_numbers

(array[string]),

pon

(string),

reason

(string | null),

record_type

(string),

rejection_code

(integer),

requested_foc_date

(string),

service_address

(string),

spid

(string),

state

(string),

status

(enum: pending, authorized, ported, rejected, rejected-pending, canceled),

support_key

(string),

updated_at

(string),

user_id

(uuid),

vendor

(uuid),

zip

(string)

telnyx-porting-out-javascript

NPX Install

Tags

SKILL.md Content

Telnyx Porting Out - JavaScript

Installation

Setup

Error Handling

Important Notes

List portout requests

List all port-out events

Show a port-out event

Republish a port-out event

List eligible port-out rejection codes for a specific order

List port-out related reports

Create a port-out related report

Retrieve a report

Get a portout request

List all comments for a portout request

Create a comment on a portout request

List supporting documents on a portout request

Create a list of supporting documents on a portout request

Update Status