Requests and responses

The Telnyx REST API base URL is https://api.telnyx.com/v2. Use the API reference as the contract for each operation. It defines the supported method, path, authentication, query parameters, request media type, response schema, and status codes.

Construct a request

A typical JSON request contains:

POST /v2/<resource> HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer <TELNYX_API_KEY>
Accept: application/json
Content-Type: application/json

{...}

Send Authorization: Bearer <TELNYX_API_KEY> when the operation declares Bearer authentication.
Send Accept: application/json for JSON REST responses.
Send Content-Type: application/json only when a body is present and the operation accepts JSON.
Do not set multipart or form media types unless the endpoint reference declares them.

Select the HTTP method

GET retrieves a resource or collection without requesting a state change.
POST creates a resource or invokes an action.
PATCH updates fields on an existing resource.
DELETE removes a resource.

Never infer that a path supports a method. Use the operation shown in the API reference.

Read successful responses

Many REST operations return a top-level data member. A single-resource response commonly uses an object:

{
  "data": {
    "id": "resource_id",
    "record_type": "resource_type"
  }
}

Collection operations commonly use a data array and can include pagination metadata:

{
  "data": [],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_results": 0
  }
}

The endpoint schema is authoritative. Do not assume every operation returns data, meta, or JSON. Common success statuses include 200 OK, 201 Created, 202 Accepted, and 204 No Content. Read the operation reference before deciding whether to parse a body or poll an asynchronous resource.

Read error responses

General REST failures commonly return an errors array:

{
  "errors": [
    {
      "code": "10004",
      "title": "Missing required parameter",
      "detail": "A required parameter was missing.",
      "source": {
        "pointer": "/data/attributes/example"
      }
    }
  ]
}

Use all available fields:

code: Stable Telnyx error identifier when supplied.
title: Short error classification.
detail: Request-specific explanation.
source.pointer: JSON Pointer to the invalid request member.
source.parameter: Invalid query parameter.
meta: Additional product-specific context.

See API error codes. Product APIs can define additional errors and envelopes, so inspect the operation reference before implementing a parser.

Handle status codes

400 or 422: Correct the request; do not retry unchanged input.
401: Restore a valid credential and Bearer header.
403: Check account access, resource ownership, verification, and product prerequisites.
404: Verify the path and resource identifier.
409: Reconcile current resource state before retrying.
429: Respect rate-limit guidance and delay the next attempt.
5xx: Treat as potentially transient, subject to operation safety and the retry guidance.

Protocol boundaries

These conventions describe Telnyx REST operations. S3-compatible Cloud Storage, WebRTC, WebSocket APIs, and webhook deliveries have separate protocol contracts in their product documentation.

​Construct a request

​Select the HTTP method

​Read successful responses

​Read error responses

​Handle status codes

​Protocol boundaries

​Related