Telnyx Porting Out - curl
Installation
# curl is pre-installed on macOS, Linux, and Windows 10+Setup
export TELNYX_API_KEY="YOUR_API_KEY_HERE"All examples below use $TELNYX_API_KEY for authentication.
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:
# Check HTTP status code in response
response=$(curl -s -w "\n%{http_code}" \
-X POST "https://api.telnyx.com/v2/messages" \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')
case $http_code in
2*) echo "Success: $body" ;;
422) echo "Validation error — check required fields and formats" ;;
429) echo "Rate limited — retry after delay"; sleep 1 ;;
401) echo "Authentication failed — check TELNYX_API_KEY" ;;
*) echo "Error $http_code: $body" ;;
esacCommon error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).
Important Notes
- Pagination: List endpoints return paginated results. Use
page[number]andpage[size]query parameters to navigate pages. Checkmeta.total_pagesin the response.
List portout requests
Returns the portout requests according to filters
GET /portouts
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts"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
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/events"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}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/events/550e8400-e29b-41d4-a716-446655440000"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
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/portouts/events/550e8400-e29b-41d4-a716-446655440000/republish"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}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/rejections/329d6658-8f93-405d-862f-648776e8afd7"Returns: code (integer), description (string), reason_required (boolean)
List port-out related reports
List the reports generated about port-out operations.
GET /portouts/reports
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/reports"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
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/portouts/reports"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}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/reports/550e8400-e29b-41d4-a716-446655440000"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}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/550e8400-e29b-41d4-a716-446655440000"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
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/550e8400-e29b-41d4-a716-446655440000/comments"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)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/portouts/550e8400-e29b-41d4-a716-446655440000/comments"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
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/portouts/550e8400-e29b-41d4-a716-446655440000/supporting_documents"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])
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/portouts/550e8400-e29b-41d4-a716-446655440000/supporting_documents"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)
curl \
-X PATCH \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "I do not recognize this transaction"
}' \
"https://api.telnyx.com/v2/portouts/550e8400-e29b-41d4-a716-446655440000/{status}"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)