--- name: telnyx-porting-out-curl description: >- Manage port-out requests when numbers are being ported away from Telnyx. List, view, and update port-out status. This skill provides REST API (curl) examples. metadata: author: telnyx product: porting-out language: curl generated_by: telnyx-ext-skills-generator --- # Telnyx Porting Out - curl ## Installation ```text # curl is pre-installed on macOS, Linux, and Windows 10+ ``` ## Setup ```bash 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: ```bash # 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" ;; esac ``` Common 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]` and `page[size]` query parameters to navigate pages. Check `meta.total_pages` in the response. ## List portout requests Returns the portout requests according to filters `GET /portouts` ```bash 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` ```bash 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}` ```bash 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` ```bash 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}` ```bash 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` ```bash 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` ```bash 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}` ```bash 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}` ```bash 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` ```bash 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) ```bash 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` ```bash 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]) ```bash 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) ```bash 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)