Introduction
Telnyx is a real-time communications platform with full, feature-rich functionality, making it quick and easy to set up and port numbers around the world, configure messaging, control VoIP and IP network functions, and define how and where communications can be used in real time. The Telnyx API can power a host of specialty applications, from call tracking to cloud-based PBX, dynamic security, and authentication use cases.
Our API Reference is organized by topics, such as Phone Numbers or Messaging. Each topic is prefaced with a general overview that describes how our API can be used within the context of that topic, followed by reference documentation of specific API endpoints.
Telnyx strives to create a developer-first platform with top tier documentation and 24/7 support. Explore our API capabilities, and please let us know how we can further empower your development team to better serve your customers.
BASE URL
https://api.telnyx.com/v2
CLIENT LIBRARIES
pip install telnyx
gem install telnyx
npm install telnyx
composer require telnyx/telnyx-php
// Maven
<dependency>
<groupId>com.telnyx.sdk</groupId>
<artifactId>telnyx</artifactId>
<version>1.2</version>
</dependency>
// Gradle
compile group: 'com.telnyx.sdk', name: 'telnyx', version: '1.2'
nuget install Telnyx.net
Overview
MISSION CONTROL PORTAL
You will need a Mission Control Portal account in order to access our API. Most of the API Reference topics will be familiar to you if you've used the Portal interface before; for example, the Connections page corresponds to the Connections API topic. You will be able to perform all the same Portal actions through the API.
PROTOCOLS
Telnyx HTTP endpoints are RESTful, and consume and return JSON. All HTTP endpoints require an API Key in the request header.
More information on API Keys and Authorization headers in the Authentication section below.
GLOSSARY
Term | Description |
---|---|
Numbers | DIDs and toll-free numbers that can be purchased and managed in order to receive calls (inbound/origination) |
Messaging | Short Message Service (SMS) text messaging. Long code |
Porting | Transferring of DIDs and toll-free numbers onto the Telnyx network from another carrier |
Connections | Provisions SIP trunks |
Call Control Applications | Configure webhooks and voice settings for call control. This resource provisions SIP trunks for call control use cases. |
Reports | Access Call and Messaging Detail Records, and generate usage reports |
Account | Your Mission Control Portal account |
HTTP ENDPOINTS
https://api.telnyx.com/v2/available_phone_numbers
https://api.telnyx.com/v2/number_orders
https://api.telnyx.com/v2/messaging_hosted_number_orders
https://api.telnyx.com/v2/number_reservations
https://api.telnyx.com/v2/phone_numbers
https://api.telnyx.com/v2/inbound_channels
https://api.telnyx.com/v2/messages
https://api.telnyx.com/2010-04-01/Accounts/{organization_id}/Messages.json
https://api.telnyx.com/v2/messaging_profiles
https://api.telnyx.com/v2/connections
https://api.telnyx.com/v2/credential_connections
https://api.telnyx.com/v2/ip_connections
https://api.telnyx.com/v2/fqdn_connections
https://api.telnyx.com/v2/call_control_applications
https://api.telnyx.com/v2/texml_applications
https://api.telnyx.com/v2/calls
https://api.telnyx.com/v2/conferences
https://api.telnyx.com/v2/outbound_voice_profiles
https://api.telnyx.com/v2/billing_groups
https://api.telnyx.com/v2/inbound_channels
https://api.telnyx.com/v2/sim_cards
https://api.telnyx.com/v2/account
https://api.telnyx.com/v2/portouts
Versioning
This is our API V2. View our API V1 here. Note that events generated by API requests will always be structured according to the API version that you have set on your Application, or Messaging Profile resource. When configuring these resources please select the API formatting version for which you would like to receive webhooks - this can be done using the API or via configuring your Application or Messaging Profile in the Portal.
All API changes are announced in our Release Notes.
Authentication
The Telnyx API V2 uses API Keys to authenticate requests. You can view and manage your API Keys by logging into your Mission Control Portal account and navigating to the Auth V2 tab in the "Auth" section. For information regarding API V1 Authentication please refer to here.
Your API Keys carry many privileges, so be sure to keep them secure! Do not share your secret API Keys in publicly accessible areas such as GitHub, client-side code, and so forth.
To use your API Key, assign it in your SDK as shown in this quickstart guide section. Using our RESTful API, you can also make requests by passing the API Key in the Authorization
header: Authorization: Bearer <YOUR_API_KEY>"
.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Rate Limits
Requests to api.telnyx.com
are rate limited
to ensure that the API remains responsive for all users. The rate limits per user are:
Action | Path | Limit |
---|---|---|
Global (all requests) | /* | 200 requests per second |
Number Search (unauthenticated) | /available_phone_numbers | 10 requests per minute |
Number Search (authenticated) | /available_phone_numbers | 1 request per second |
Phone Numbers (authenticated) | /phone_numbers | 5 requests per second |
Connections (authenticated) | /connections | 5 requests per second |
FQDN Connections (authenticated) | /fqdn_connections | 5 requests per second |
IP Connections (authenticated) | /ip_connections | 5 requests per second |
Credential Connections (authenticated) | /credential_connections | 5 requests per second |
Call Control Applications (authenticated) | /call_control_applications | 5 requests per second |
TeXML Applications (authenticated) | /texml_applications | 5 requests per second |
Fax Applications (authenticated) | /fax_applications | 5 requests per second |
Outbound Voice Profiles (authenticated) | /outbound_voice_profiles | 5 requests per second |
Number Orders (authenticated) | /number_orders | 1 request per second |
Messaging Profiles (authenticated) | /messaging_profiles | 5 requests per second |
When the rate limit is exceeded responses with status code 429 will be returned indicating that you have exhausted the number of requests allowed in the current window.
To avoid exceeding the limits we recommend that you proactively limit the rate of requests made by your application.
These limits are subject to change based on usage and may be adjusted to align with changes in capacity.
Over your rate limit?
Contact [email protected] if you find you are exceeding the rate limit.
RATE LIMIT RESPONSE BODY
{
"errors": [
{
"code": "10011",
"title": "Too many requests",
"detail": "You have exceeded the maximum number of allowed requests."
}
]
}
The status code of this response is 429.
Parameters and Field Names
The Parameter & Field Names section provides an overview of patterns for API request and response parameter and field names.
HTTP Headers
Date-times in HTTP headers follow RFC-7231 §7.1.1.1's recommended "IMF-fixdate" format.
An example of the preferred format is
Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate
Booleans
Boolean values are presented as true
and false
values. They will not be 1
or 0
nor will they be strings such as "true" and "false".
Date-times
All date-times are represented in UTC with precisely the following format: YYYY-MM-DDThh:mm:ss.fffZ
where fff
is the first three decimals of the fractional seconds (i.e., millisecond precision).
API V2 accepts date-times in at least the following formats:
YYYY-MM-DDThh:mm:ss.fffZ
YYYY-MM-DDThh:mm:ssZ
YYYY-MM-DDThh:mmZ
- The above with
-00
,-0000
, or-00:00
instead of theZ
timezone identifier.
Times (no date portion)
All times are represented in UTC with precisely the following format: hh:mm:ss.fffZ
where fff
is the first three decimals of the fractional seconds (i.e., millisecond precision).
Durations
If a parameter represents a unit of time, then the unit name should be part of the field name so that the consumer knows what the value represents. For example, a retry timeout value would be named retry_timeout_secs
or retry_timeout_millis
.
Valid field suffixes are:
- millis
- secs
- hours
- days
- weeks
- months
- years
API V2 does not use ISO8601 time durations (e.g. P4Y
, PT0,42M
or P3Y6M4DT12H30M5.423S
).
Time zones
Time zone field names are always spelled as timezone
and the value is always the Time Zone Database area name spelled out as Europe/Berlin
, America/Chicago
for example.
Date Literals
User-friendly date ranges use this naming convention.
Date Literal | Range |
---|---|
yesterday | Starts 00:00:00 the day before and continues for 24 hours. |
today | Starts 00:00:00 of the current day and continues for 24 hours. |
tomorrow | Starts 00:00:00 after the current day and continues for 24 hours. |
last_week | Starts 00:00:00 on the first day of the week before the most recent first day of the week and continues for seven full days. |
this_week | Starts 00:00:00 on the most recent first day of the week before the current day and continues for seven full days. |
next_week | Starts 00:00:00 on the most recent first day of the week after the current day and continues for seven full days. |
last_month | Starts 00:00:00 on the first day of the month before the current day and continues for all the days of that month. |
this_month | Starts 00:00:00 on the first day of the month that the current day is in and continues for all the days of that month. |
next_month | Starts 00:00:00 on the first day of the month after the month that the current day is in and continues for all the days of that month. |
last_N_hours | For the number n provided, starts at 00 of the last hour and continues for the past n hours. |
next_N_hours | For the number n provided, starts at 00 of the next hour and continues for the next n hours. |
last_N_days | For the number n provided, starts 00:00:00 of the current day and continues for the past n days. |
next_N_days | For the number n provided, starts 00:00:00 of the current day and continues for the next n days. |
last_N_weeks | For the number n provided, starts 00:00:00 of the last day of the previous week and continues for the past n weeks. |
next_N_weeks | For the number n provided, starts 00:00:00 of the first day of the next week and continues for the next n weeks. |
Enums and String Literals
Enum and string literal parameters use snake case. If there is an acronym involved, there will not be an underscore between every letter.
For example, by_ani
instead of ByANI
, byAni
, or by_a_n_i
.
Country Codes
The field name country_code
is always used to represent a country. It will be in ISO 3166-1 alpha-2 format in capital letters to represent the country. For example DE
for Germany.
Addresses
Addresses are represented like this:
E.g.
{
"street_address": "311 W Superior St",
"extended_address": "Suite 504",
"locality": "Chicago",
"administrative_area", "IL"
"country_code": "US",
"postal_code": "60654"
}
U.S. Addresses
US states are always represented in their two-digit form in capital letters. For example, NY
for New York.
City Names
City names are always called locality
and represented in title case. For example, New York City
instead of NEW YORK CITY
.
Phone Numbers
Phone numbers are always specified in e164 format. For example, +18005550199
.
If the country calling code needs to be represented in the API, the field name will always be country_calling_code
. If representing the actual country via its alpha 2 representation, country_code
will be used.
Ex: {"country_calling_code": "1", "country_code": "US"}
PAGINATION
The parameter which contains pagination is page
. This parameter is a map of pagination attributes.
Example
GET /phone_numbers?page[number]=3&page[size]=1 HTTP/1.1
The default number of items per page is 20; however, sometimes, this may not be appropriate.
Page numbering is 1-based and omitting the page
, or the page[number]
parameter will return the first page.
Generally speaking, the maximum allowable results will not be more than 250, although there may be some exceptions to this rule.
The total number of results is provided in the total_pages
field so that clients will know how many page options to display.
SORTING
An endpoint may support requests to sort the primary data with a sort
query parameter.
Example
GET /connections?sort=name HTTP/1.1
Unless not appropriate, the default sort will be created_at DESC
An endpoint may also support multiple sort fields using the array syntax. Sort fields will be applied in the order specified.
Example
GET /connections?sort[]=name&sort[]=created_at HTTP/1.1
The sort order for each sort field will be ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, “-“), in which case it will be descending.
GET /connections?sort[]=-created_at&sort[]=name HTTP/1.1
The above example should return the newest connections first. Any connections created on the same date will then be sorted by their name in ascending alphabetical order.
FILTERING
Filtering of a resource collection based upon associations do so by allowing query parameters that combine the filter with the association name.
For example, the following is a request for all phone_numbers associated with a particular tag:
GET /phone_numbers?filter[tag]=tag_one HTTP/1.1
Filtering two values within an array can be achieved using query parameter array syntax:
GET /phone_numbers?filter[tag][]=tag_one&filter[tag][]=tag_two HTTP/1.1
GET /comments?filter[tag]=tag_one,tag_two HTTP/1.1
Use the string null
to filter on resources that don't have a particular value set:
GET /comments?filter[author]=null HTTP/1.1
FILTERING ON VALUES OF NESTED OR RELATED OBJECTS
In order to denote that a filter applies to an attribute of a nested object, use the dot notation.
For example, the phone numbers endpoint returns data in this format:
{
"id": "d460a653-8ee6-4061-ae9a-5b8a52539fb4",
"phone_number": "18005550199",
"record_type": "phone_number",
...
"voice": {
"e911_address_id" : "",
"connection_name" : false,
"inbound_call_recording_channels" : "single",
...
}
}
In order to filter by the connection name the path and request would look like:
GET /phone_numbers?filter[voice.connection_name]=conn_one HTTP/1.1
Similarly by connection id:
GET /phone_numbers?filter[voice.connection_id]=d460a653-8pp6-4061-ae9a-5b8a57339fb4 HTTP/1.1
However, if name
was a top-level key as in the below example:
{
"id": "d460a653-8pp6-4061-ae9a-5b8a57339fb4",
"name": "conn_one",
"record_type": "connection",
...
}
then the query would be:
GET /connections?filter[name]=conn_one HTTP/1.1
COMPLEX FILTERS
When filtering, you may need to specify more complex filters than equal to
.
Options are:
eq
ne
gt
gte
lt
lte
starts_with
ends_with
contains
Return phone numbers purchased before 2018-02-21:
GET /phone_numbers?filter[purchased_at][lt]=2018-02-21 HTTP/1.1
If using eq
then:
GET /phone_numbers?filter[purchased_at][eq]=2018-02-21 HTTP/1.1
and:
GET /phone_numbers?filter[purchased_at]=2018-02-21 HTTP/1.1
are equivalent.
To filter using string data use starts_with
, ends_with
or contains
:
GET /phone_numbers?filter[voice.connection_name][contains]=conn HTTP/1.1
Requests
Requests to any API endpoint should be in the JSON format, with rare exceptions made for allowing other request types when needed (such as for file uploads).
Lower Case Paths and Attributes
Lower case and snake_case
path names are used throughout the API.
api.telnyx.com/v2/messaging_profiles
api.telnyx.com/v2/available_phone_numbers
Attributes also use lower case syntax, and use underscore separators so that attribute names can be typed without quotes in JavaScript, e.g.:
test_attribute: "test"
Query parameters use lower case keys and underscores as separators:
api.telnyx.com/v2/phone_numbers?phone_number=+18005550100
Metadata in requests
Metadata about records is generally not needed in requests made to API endpoints. For example, a POST to /connections
is understood to be an attempt to create a Connection, and you do not need to specify in your request that you are making a Connection. The data sent by the client is understood to be that for a Connection, and it will be rejected if it does not specify a valid Connection.
$ curl -X POST https://api.telnyx.com/v2/connections \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"name": "conn_one", "active": true}'
{
"data": {
"record_type": "connection",
"id": "9ac0da9f-173f-4ebd-8f16-6e4d9585a0b2",
"name": "conn_one",
...
"active": true
}
}
Resource names
The plural version of a resource name is used unless the resource in question is a singleton within the system (for example, the overall status of the system might be /status
). This keeps it consistent in the way you refer to particular resources.
Actions
Actions are clearly delineated by the actions
prefix:
/resources/:resource/actions/:action
e.g., to register a particular SIM card:
/sim_cards/:id/actions/register
Actions may also be used on collections using a top-level delineation to avoid namespace conflicts and clearly show the scope of the action:
/actions/:action/resources
e.g., to activate all SIM cards:
/actions/activate/sim_cards
CREATE A RESOURCE
A resource can be created by sending a POST
request to a URL that represents a collection of resources.
The body of the response will contain at least a record_type
member, although in most cases it will also have an id
:
$ curl -X POST https://api.telnyx.com/v2/connections \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"name": "conn_one"}'
# Example response
{
"data": {
"record_type": "connection",
"id": "9ac0da9f-173f-4ebd-8f16-6e4d9585a0b2",
"name": "conn_one",
...
}
}
201 Created
If a resource has been created successfully, the server will return a 201 Created
status code.
The response will also include the primary resource created:
# Example response
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"record_type": "connection",
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "conn_one",
...
}
}
202 Accepted
If a request to create a resource has been accepted for asynchronous processing, the server will return a 202 Accepted
status code.
UPDATING A RESOURCE
A resource can be updated by sending a PATCH
request to the URL that represents the resource.
$ curl -X PATCH https://api.telnyx.com/connections/v2/9ac0da9f-173f-4ebd-8f16-6e4d9585a0b2 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"name": "conn_one"}'
# Example response
{
"data": {
"record_type": "connection",
"id": "9ac0da9f-173f-4ebd-8f16-6e4d9585a0b2",
"name": "conn_one",
...
}
}
If a request does not include all of the attributes for a resource, the server will interpret the missing attributes as if they were included with their current values. The server will not interpret missing attributes as null values. To explicitly set something to null, it must be included in the request with a null value.
202 Accepted
If an update request has been accepted for asynchronous processing, the server will return a 202 Accepted
status code.
200 OK
If a server successfully updates the resource, it will return a 200 OK
response. The response document will include a representation of the updated resource as if a GET
request was made to the request URL.
DELETE A RESOURCE
$ curl -X DELETE https://api.telnyx.com/v2/connections/9ac0da9f-173f-4ebd-8f16-6e4d9585a0b2\
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
An individual resource can be deleted by making a DELETE
request to the resource’s URL.
202 Accepted
If a deletion request has been accepted for asynchronous processing, the server will return a 202 Accepted
status code.
204 No Content
The server will return a 204 No Content
status code if a deletion request is successful and no content is returned.
200 OK
The server will return a 200 OK
status code if a deletion request is successful.
404 Not Found
The server will return a 404 Not Found
status code if a deletion request fails due to the resource not existing.
Responses
All endpoints will respond with JSON unless another format is specifically requested and supported. Our JSON responses use a format inspired by, but not directly based on, the JSON API specification.
The outermost object in a response will contain the actual response data under a top-level key of data
. If there was errors, the top-level key will be errors
and not data
- see errors section for details.
High-level metadata will be included in the response along with the data
object if needed.
In addition, all records in a response will include a record_type
field which specifies the type of data it represents. This record_type
should remain the same regardless of which endpoint the data is returned from.
For example, GET /v2/messaging_profiles/123
might have the following as a response:
{
"data": {
"record_type": "messaging_profile",
"id": "123",
"name": "MP_one",
"webhook_url": "example.com/callback"
}
}
The value for data
should be a JSON object (single record) for responses from endpoints that return a single entity or an array of JSON objects from endpoints that return multiple records. This must be consistent; a single endpoint will never use a single object some of the time and an array at other times.
For example, GET /v2/messaging_profiles
will always use an array, even if there is only one record, or even no records:
{
"data": [
{
# ...
},
{
# ...
}
]
}
While GET /v2/messaging_profiles/:id
will always use a single JSON object:
{
"data": {
# ...
}
}
Webhooks
One application can provide another application with real-time updates via a webhook (also referred to as a web callback or HTTP push API). A webhook delivers data to other applications as it happens, meaning you get data immediately. In the past, APIs would typically need to poll for data very frequently to get it promptly. This makes webhooks much more efficient for both provider and consumer. The only drawback to webhooks is the difficulty of initially setting them up - this tutorial walks through how to consume webhooks for Telnyx Messaging.
Webhooks are sometimes referred to as “Reverse APIs,” as they give you what amounts to an API spec, and you must design an API for the webhook to use. The webhook will make an HTTP request to your app (typically a POST), and you will then be charged with interpreting it.
Telnyx can send webhook events that notify your application any time an event happens on your account. This is especially useful for events like receiving an SMS or MMS message and getting feedback on Call Control events. The Messaging webhooks section goes into a bit more detail on how Messaging webhooks work.
HTTP and HTTPS
- Unsecure (HTTP) URLs are allowed for webhooks.
- If HTTPS (TLS) is used, the certificate will be validated.
Event Type Naming
Where possible, events map to the C(R)UD operations, but this is certainly not always applicable.
- resource.created
- resource.updated
- resource.deleted
When the CRUD operations are not applicable, events will be named with past tense verbs.
- message.sent
- message.deleted
message.finalized
porting_sub_request.ported
- porting_sub_request.closed
Responding to a webhook
To acknowledge receipt of a webhook, your endpoint should return a 2xx
HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx
codes, will indicate to Telnyx that you did not receive the webhook. URL redirection or a "Not Modified" response will be treated as a failure.
Retries
Webhooks will be retried to each of the supplied URLs if your application does not respond in 2000 milliseconds. This can be configured on your Application or Messaging Profile. If all supplied webhook URLs timeout repeatedly we may delay or abandon some webhooks for a brief period of time.
Best Practices
If your webhook script performs complex logic or makes network calls, it's possible the script would timeout before Telnyx sees its complete execution. For that reason, you may want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx
HTTP status code, and then perform the rest of its duties.
Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events. Additionally, we recommend verifying webhook signatures to confirm that received events are being sent from Telnyx.
Webhook Signing
Telnyx signs the webhook events it sends to clients so that the authenticity of the request can be verified. Webhook signing in API V2 uses public key encryption. Telnyx stores a public-private key pair and uses the private key to sign the payload. The public key is available to you so that you can verify the request.
The public key can be viewed in the Mission Control Portal.
The signature for the payload is calculated by building a string that is the combination of the timestamp of when the request was initiated, the pipe |
character and the JSON payload. The signature is then Base64
encoded.
Base64.encode64("#{timestamp}|#{payload}")
The signature (Base64
encoded) and the timestamp (in Unix format) are assigned to the request headers telnyx-signature-ed25519
and telnyx-timestamp
respectively.
You can then use cryptographic libraries in your language of choice to verify the signature using the public key. For examples, please see:
STRUCTURE
The top-level structure of API v2 webhooks will always contain a data
object and may also contain a meta
object if applicable . For example, Call Control webhooks don't have a meta
object in their payload whereas Messaging webhooks do. Generally, the payload
of the webhook contains the most valuable information for your application.
Call Control Top-Level Structure
{
"data": {
"event_type": "call.answered",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
"call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
"call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"connection_id": "7267xxxxxxxxxxxxxx",
"from": "+18005550100",
"state": "answered",
"to": "+18005550199"
},
"record_type": "event"
}
}
FIELD NAME | DESCRIPTION |
---|---|
call_control_id | The ID used in sending commands to the Telnyx API. |
call_leg_id | ID that is unique to the call and can be used to correlate webhook events. |
call_session_id | ID that is unique to the call session and can be used to correlate webhook events. |
event_type | The type of event being delivered which also determines the structure of the payload . |
id | Unique ID of the event. |
occurred_at | ISO 8601 datetime of when the event occurred. |
record_type | Will always be event . |
Messaging Top-Level Structure
{
"data": {
"event_type": "message.sent",
"id": "1f1243a9-93a5-48d1-bf4b-d680b03565a0",
"occurred_at": "2020-04-30T20:58:39.421+00:00",
"payload": {
...
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "https://hookb.in/G9J9pghfoeZJcpadWdQoxm"
}
}
FIELD NAME | DESCRIPTION |
---|---|
event_type | The type of event being delivered which also determines the structure of the payload . |
id | Unique ID of the event. |
occurred_at | ISO 8601 datetime of when the event occurred. |
payload | The main data for the event. The structure is denoted by the event_type . |
record_type | Will always be event . |
attempt | The number of attempts made to deliver the webhook. Multiple attempts will occur if your application does not send Telnyx a 2xx HTTP status code within 2s of receipt of the webhook. |
delivered_to | URL that the webhook was sent to. |
Errors
ERROR FORMATTING
We include known causes and possible solutions so that API users can write logic to handle errors intelligently and debug quickly. When one or more errors are present, the top-level key in the response will be errors
and not data
. The value for errors
will always be an array, and there will always be at least one error present when this is returned.
ERROR COMPONENTS
An error object is made up of the following required members:
code
: an application-specific error code, expressed as a stringified 5-digit integer [e.g. "10001"
].
title
: a short, human-readable summary of the problem.
An error object may have the following members:
detail
: a human-readable explanation specific to this occurrence of the problem.
source
: an object containing references to the source of the error, optionally including any of the following members:
pointer
: a JSON Pointer [RFC6901] to the associated entity in the request document e.g."/"
for a primary object, or"/title"
for a specific attribute.parameter
: a string indicating which URI query parameter caused the error.
meta
: a meta object containing non-standard meta-information about the error. This will likely be a URL to the relevant documentation.
Example of field-level error
Using the pointer to indicate exactly which field is invalid.
HTTP/1.1 422 Unprocessable Entity
{
"errors":[
{
"code":"10006",
"title":"Invalid resource ID",
"detail":"The provided resource ID was invalid",
"source":{
"pointer":"/id"
},
"meta":{
"url":"https://developers.telnyx.com/docs/api/v2/overview/errors/10006"
}
}
]
}
Example of request level error
Omitting the source attribute entirely.
HTTP/1.1 404 Resource Not Found
{
"errors":[
{
"code":"10005",
"title":"Resource not found",
"detail":"The requested resource or URL could not be found.",
"meta":{
"url":"https://developers.telnyx.com/docs/overview/errors/10005"
}
}
]
}