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 called. E.164 format. See NOTE 1 below. |
| call_party | Yes | "terminating" |
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:
https://api.truecnam.net/api/v1?username=APIkey&password=APIpassword&resp_type=extended&resp_format=json&calling_number=12125551212&called_number=16465557000&call_party=terminating
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 |
calling_number |
No | Yes | Yes | String | calling_number submitted in query |
called_number |
No | No | Yes | String | called_number submitted in query |
proposed_calling_number |
No | No | Yes | String | TrueCLID proposed calling number. See this article. |
cnam_match |
No | No | Yes | Boolean | Is CNAM available for calling_number ? |
name |
Yes | Yes | Yes | String | CNAM short of calling_number (15 char or less) |
extended_name |
No | No | Yes | String | CNAM long of calling_number (Up to 255 char) |
true_clid |
No | No | Yes | String | TrueCLID indicator. See this article. |
spam_score_match |
No | No | Yes | Boolean | Is a TrueSpam score available for calling_number ? |
spam_score |
No | No | Yes | Integer | TrueSpam score (0-100) for calling_number - See this article. |
queries_per_minute_remaining |
No | No | Yes | Integer | Queries remaining on your account this minute |
queries_per_day_remaining |
No | No | Yes | Integer | Queries remaining on your account today (GMT/UTC timezone) |
err |
No | Yes | Yes | String | Error number |
error_msg |
No | Yes | Yes | String | Error description text |
{"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.