Telnyx API v1 Reference' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Introduction' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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 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 first-rate interactive documentation and 24/7 support. Explore our API capabilities and please let us know how we can better empower your development team to better serve your customers.
HOSTS
https://api.telnyx.com
https://sms.telnyx.com
https://data.telnyx.com
https://lrnlookup.telnyx.com
API EXPLORER
You can use the API Explorer to try out API endpoints, side-by-side with the endpoint reference.
Telnyx does not offer a sandbox environment for the API Explorer at this time. You can create a separate, development-only Mission Control Portal account to test out API endpoints. The API Explorer triggers real API calls, so do not use your production Mission Control account credentials when testing.
Overview' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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 except
sms.telnyx.com/messages
require an API token value in the request header.
More information on API tokens, Authorization headers and IP Authentication will be covered in the Authentication section below.
CNAM Data and LRN Data may be retrieved with HTTP, as well as DNS ENUM, SIP
(LRN only) or XML UDP
(LRN only) protocols. DNS ENUM, SIP and XML UDP requests must be set up to use an IP authenticated profile. More information on IP Authentication will be covered 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 |
Reports | Access Call and Messaging Detail Records, and generate usage reports |
Account | Your Mission Control Portal account |
CNAM Data | Caller ID Name information |
LRN Data | Local Routing Number information |
Switch Data | Telephone switch information |
HTTP ENDPOINTS
https://api.telnyx.com/origination
https://api.telnyx.com/termination
https://api.telnyx.com/messaging
https://api.telnyx.com/reporting
https://api.telnyx.com/security
https://api.telnyx.com/account
https://data.telnyx.com/caller-information
https://data.telnyx.com/LRN
https://data.telnyx.com/LRNLookup
https://sms.telnyx.com/messages
DNS ENUM ENDPOINTS
data.telnyx.com
lrnlookup.telnyx.com
SIP ENDPOINTS
lrnlookup.telnyx.com
XML UDP ENDPOINTS
lrnlookup.telnyx.com
Versioning' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
This is our API V1. View our API V2 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' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Log in to your account in order to obtain the API access keys needed to authenticate your application.
API USER AND TOKEN
API User may either be your Portal email address or your 24-character API Access Key. You can find your API Access Key and API token under Auth in the Portal.
Add an API Token if you have not done so already. Once you have your API user and token, you may use them as header values in HTTP requests.
IP AUTHENTICATION
CNAM & LRN Data endpoints that do not use HTTP will require IP authentication. You will need to add IPs to a connection. You can then create a data profile through the Portal Telco Data interface and choose IP Address as the authentication method, and then select the connection with the IPs you’d like to whitelist. You can read more on how to authenticate specific endpoints in the CNAM Data and LRN Data Overviews.
SENDING SMS
An API token is not required to send SMS. Create a new Messaging profile to obtain a messaging profile secret to add to your HTTP headers. More in-depth information on sending SMS can be found in the Messaging Overview.
GLOSSARY
Term | Description |
---|---|
API User | Your Portal account email address or API Access Key |
API Access Key | Access key used in place of your Portal email address as the API user |
API Token | Token generated within your Telnyx account to use with API requests |
IP Authentication | Uses IP addresses as the authentication method, as opposed to token-based authentication |
Profile Secret | Messaging profile token used to authenticate SMS send requests |
EXAMPLE USER & TOKEN REQUEST HEADER
x-api-user: example@telnyx.com
x-api-token: MY_TOKEN
EXAMPLE SMS (SEND) REQUEST HEADER
x-profile-secret: MY_TOKEN
Rate Limits' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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) | /* | ~40 requests per second |
Number Search (unauthenticated) | /origination/number_searches | ~10 requests per minute |
Number Search (authenticated) | /origination/number_searches | ~40 requests per second |
Number Update | /origination/numbers/{id} | ~60 requests per minute |
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 support@telnyx.com 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.