Getting Started

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 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.

Base URL

https://api.telnyx.com/v2


Client Libraries
pip install telnyx

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.


Versioning

This is our API V2. View our API V1 here.


Glossary

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
HTTP Endpoints

https://api.telnyx.com/v2/available_phone_numbers
https://api.telnyx.com/v2/number_orders
https://api.telnyx.com/v2/number_reservations
https://api.telnyx.com/v2/messages
https://api.telnyx.com/v2/messaging_profiles
https://api.telnyx.com/v2/messaging_phone_numbers
https://api.telnyx.com/v2/alphanumeric_sender_ids



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.



cURL Authenticated Request
curl -X GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/messaging_profiles?page[size]=10"

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) /* 40 requests per second
Number Search (unauthenticated) /available_phone_numbers 10 requests per minute
Number Search (authenticated) /available_phone_numbers 40 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 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.

Errors

CodeDescription