CNAM query API call

Modified on: 2015-06-04 20:39:09 UTC

The CNAM query allows you to pull Caller ID Name (CNAM) from the TrueCNAM database for a phone call you are receiving. Below are the request fields you will send:

Field Required Value Comment
username Yes API Key Username Not the web login username. Used to authenticate your account.
password Yes API Key Password Not the web login password. Used to authenticate your account.
resp_type No

If passed: "simple", "basic", "extended"

Optional, allows specifying response type on per-query basis. If not passed, will use account default.
resp_format No If passed: "csv", "json", "xml" Optional, allows specifying response format on per-query basis. If not passed, will use account default. See this.
calling_number Yes

E.164 number that is calling you

This is the number that is calling you, and you wish to request CNAM information for. E.164 format (including Country Code).

called_number No E.164 number that is being called This is the number that is being calledE.164 format. See NOTE 1 below.
call_party Yes


This specifies that you are requesting CNAM for a call terminating to you.

NOTE 1: called_number - Optional field, this should be the number that is being CALLED only. If the called number is not available, may be uncertain, or you do not want to send this information, you do not need to send this. Do not send or static or incorrect information in this field. TrueCLID information will not be returned if field is excluded. We anonymously aggregate this information to help calculate TrueSpam scores. See our Privacy Policy for details.

Below is an example of a request using both the mandatory and optional fields, including example value data:

Response Fields:

The fields within the table below are organized in the same order as a response in CSV format will be returned (other formats will include the field name in response). Depending on the resp_type you choose ("simple", "basic", "extended") certain fields will be returned as shown below:

Field simple basic extended Type Note


No Yes Yes String

calling_number submitted in query


No No Yes String

called_number submitted in query


No No Yes String

TrueCLID proposed calling number. See this article.


No No Yes Boolean

Is CNAM available for calling_number ?


Yes Yes Yes String

CNAM short of calling_number (15 char or less)


No No Yes String

CNAM long of calling_number (Up to 255 char)


No No Yes String

TrueCLID indicator. See this article.


No No Yes Boolean

Is a TrueSpam score available for calling_number ?


No No Yes Integer

TrueSpam score (0-100) for calling_number - See this article.


No No Yes Integer

Queries remaining on your account this minute


No No Yes Integer

Queries remaining on your account today (GMT/UTC timezone)


No Yes Yes String

Error number


No Yes Yes String

Error description text

Here's an example of a response in extended json format: 
{"called_number": "16465557000", "proposed_calling_number": "", "extended_name": "New York City Information", "queries_per_minute_remaining": 9, "queries_per_day_remaining": 999, "spam_score": 0, "calling_number": "12125551212", "spam_score_match": 1, "err": "0", "true_clid": "unknown", "cnam_match": 1, "error_msg": "", "name": "NYC Information"}


Next, see how to use TrueCLID call start.

Did you find it helpful? Yes No

Can you please tell us how we can improve this article?