This is the API V2 documentation. To switch out of beta revert back to our API V1.

Telnyx API v2 Reference

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 NumbersAPI or MessagingAPI. 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 PortalTelnyx Developers 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 pagePORTAL corresponds to the Connections APIAPI topic. You will be able to perform all the same Portal actions through the API.

PROTOCOLS

Telnyx HTTP endpoints are RESTfulTelnyx Developers, and consume and return JSONTelnyx Developers. 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 hereAPI.

GLOSSARY

TermDescription
NumbersDIDs and toll-free numbers that can be purchased and managed in order to receive calls (inbound/origination)
MessagingShort Message Service (SMS) text messaging. Long code
PortingTransferring of DIDs and toll-free numbers onto the Telnyx network from another carrier
ConnectionsProvisions SIP trunks
ReportsAccess Call and Messaging Detail Records, and generate usage reports
AccountYour 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 PortalTelnyx Developers 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 limitedTelnyx Developers 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.comTelnyx Developers 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 429Telnyx Developers.

Errors

CodeDescription