CNAM API
This document provides in-depth instructions on how to retrieve caller information* with Tychron's Caller ID Lookup (CNAM) API. Gather key information on your callers to identify important prospects and avoid scammers. Get more out of your voice services and start building now.
*Please note that CNAM usage is limited to North American numbers only.
Restrictions
Request Endpoint
GET /api/v1/cnam/:number HTTP/1.1
Host: api.atlas.tychron.online
Request Path Parameters
Parameters marked with * are mandatory in all requests.
Parameter | Type | Default | Description |
---|---|---|---|
number * | String | An 11 digit, valid North American Numbering Plan (NANP) number. |
Request Headers
Parameters marked with * are mandatory in all requests.
Header | Default | Description | Example |
---|---|---|---|
Accept | application/json or text/plain | This header determines what output format should be returned in a response. When this header is given, it will take priority over the default output parameter (JSON). |
|
Authorization * | Please use your API Key's HTTP Token for authorization. |
|
Request Format
GET /api/v1/cnam/:number?output=json|text HTTP/1.1
Host: api.atlas.tychron.online
Accept: application/json, text/plain
Authorization: Bearer YOUR_API_KEY_HERE
Query Parameters
Parameters marked with * are mandatory in all requests.
Parameter | Type | Default | Description |
---|---|---|---|
output | String | json | Queries must be made in either json or plain text. |
Response Codes
Code | Description | Solutions |
---|---|---|
200 OK | The request was successful and should contain the requested data. | |
400 Bad Request | The payload body of the request is malformed or the request contains invalid parameters. | This error is most likely caused by a text based output with the messaging_lookup or enhanced flags set to true. Either use json as the output, or unset the messaging_lookup or enhanced flags when using a text based output. |
401 Unauthorized | The request may be deemed unauthorized due to a number of factors.
| This error typically results from using an incorrect API token in requests. Check your API token for typos. If the error persists, please contact support. (support@tychron.com) |
402 Payment Required | Your account has either an insufficient balance or you have exceeded your credit limit in the request. | Please contact (support@tychron.com) to purchase more credits. |
403 Forbidden | The user is not permitted to make the specified request(s). In this instance, the user is likely not authorized to use the CNAM API. | This error typically results from using an incorrect API token in requests. Check your API token for typos. Please contact support for additional details.(support@tychron.com) |
415 Unsupported Media Type | The content-type used to make the request is not supported. | This endpoint only requires a GET request with query parameters. Please remove the Content-Type header from your request. |
422 Unprocessable Entity | The parameters of the request body failed validation or contain invalid values. | The response body will contain specific details for the request failure. Correct the request parameters based on these details. |
500 Internal Server Error | The request has not been fulfilled due to a server error. | Please report this error and contact support for further assistance. (support@tychron.com) |
Response Headers
Name | Description | Example |
---|---|---|
X-Request-ID | An ID used to identify the HTTP request. |
|
X-CDR-ID | An ID used to identify the CDR (Call Detail Record) generated by the request. Please provide this ID for any billing questions when contacting support. |
|
Response Format
JSON
HTTP/1.1 200 OK
Content-Type: application/json
X-CDR-ID: AN_ID
{
"data": {
"number": "12003004000",
"cnam": "JOHN DOE",
"spam_type": "NONE"
}
}
Text
HTTP/1.1 200 OK
Content-Type: text/plain
JOHN DOE
Response Parameters
Parameters marked with * are mandatory in all queries.
Parameter | Type | Default | Description |
---|---|---|---|
Root | |||
data * | Data | A top-level map containing dip data. | |
errors * | List<Error> | A top-level map containing any request errors. | |
Data | |||
number * | String | The number used initially in the request. | |
cnam | String | The cname value of the number. | |
spam_type | SpamType | Denotes whether or not the number is associated with a potential SPAM caller. |
SpamType
ROBOCALL
SPAM
FRAUD
INVALID_NUMBER
NONE
cURL Examples
JSON
curl \
-H "Authorization: Bearer KEY" \
https://api.atlas.tychron.online/api/v1/cnam/12003004000
{
"data": {
"cnam":"JOHN DOE",
"number":"12003004000",
"spam_type": "NONE"
},
"errors": []
}
Text
curl \
-H "Authorization: Bearer KEY" \
https://api.atlas.tychron.online/api/v1/cnam/12003004000?output=text
JOHN DOE