This is the current API V1 documentation. Explore our API V2 if you’d like to test new features.

CNAM Data Overview

To display name information instead of a phone number when making a call, a number must be registered in a central database. For users in the United states, this database is called CNAM. CNAM enables the display of a name when a call is made to new devices that have CNAM database lookup enabled.

The Get Caller ID endpoint can be used to retrieve caller information typically for display to the user receiving the call. The CNAM Data API provides two protocols for retrieval: HTTP and DNS ENUM requests.

Note: Telnyx gives you the ability to enable inbound Caller ID Name via the Number endpoint.





Getting Started with Telco Data: CNAM

HTTP vs ENUM Requests

Typically, if your application communicates over HTTP then you will use the HTTP protocol to retrieve CNAM records. If, however, you are working with a system that has CNAM query support via Enum DNS built in then using this interface will make more sense.

Note: as ENUM requires IP Authentication, you cannot use an API token generated on the Portal to authenticate ENUM API requests.

Authentication Requirements

You will need to set up a Telco Data Profile in the Portal in order to access CNAM Data.


Telco Data Numbering and calling metadata, frequently used by telecom providers to query for call information
Telco Data Profile Used to enable and configure telco data endpoints on the Portal

Authenticating Requests

HTTP Token Authentication

HTTP requests will require an Authorization header with Token as the authentication type. To get the token value, generate a new API token from the Auth page. Name your token something unique to distinguish it from other platform API tokens, eg. "CNAM Data".

Navigate to the Telco Data Page in the Portal and add a Data Profile with the following options:

  • Authentication Method: API Token
  • Mechanism Type: HTTP
  • Data Type: CNAM

You may now use the API token you had generated in the Authorization header for all HTTP requests.

ENUM IP Authentication

To set up IP Authentication for ENUM on the Portal, create a Connection using the Connections API or the Portal interface. Set the Connection Type to IP Address.

Navigate to the Telco Data Page in the Portal and add a Data Profile with the following options:

  • Authentication Method: IP Address
  • Mechanism Type: ENUM
  • Data Type: CNAM

Your IP Address should now be authorized to use with DNS ENUM requests.


Authorization:  Token MY_TOKEN


--header "Authorization: Token MY_TOKEN"