Facebook tracking pixel
Documentation
Resources
Integration Guides

Introduction

This document details the RESTful API method for integrating OpenCNAM, which facilitates native access to calling name databases.

Quickstart

Ready to get started? Once you have signed up and created an account try out a quick curl command to query the OpenCNAM RESTful API:

curl 'https://api.opencnam.com/v3/phone/NUMBER?account_sid=SID&auth_token=TOKEN'

Note that both secure HTTPS requests and insecure HTTP requests are supported. For latency sensitive applications, HTTP requests are recommended. For security sensitive applications, HTTPS support is available.

In order to test the API without incurring charges, please use the following demonstration number: +15551234567

Sending a query using this number will return the following JSON response:

{
    "name": "SAMPLE",
    "number": "+15551234567",
    "price": 0,
    "uri": "/v3/phone/+15551234567"
}



Basics

This documentation uses a couple notes and documentation conventions that will be explained in this section.

  • Authentication is always required. To simplify the examples, however, the documentation will frequently omit showing the Authorization header or query-string account_sid and auth_token parameters.
  • The phone number should be in E.164 format, starting with a “+” followed by the country code. (For example for NUMBER use +16786318356 instead of +6786318356, 6786318356 or 678-631-8356.)
  • This documentation frequently refers to curl. Curl, or cURL, is a computer software project providing a library and command-line tool for transferring data using various protocols. Please note that many shells (e.g. bash) give special meaning to ?, &, and other characters, so you'll need to single-quote your URLs.



Passing Arguments

There are a few configuration options that you can specify via query-string when making a request to OpenCNAM. In the event of a conflict, query-string configurations will override settings from the control panel.

Response Casing (casing)

Configure the casing of the returned CNAM value using the query-string "casing" and one of the values "caps" or "title". For example, these are all valid requests with a specified casing:

https://api.opencnam.com/v3/phone/+16786318356?format=json&casing=caps
https://api.opencnam.com/v3/phone/+16786318356?format=json&casing=title
https://api.opencnam.com/v3/phone/+16786318356?casing=caps

Mobile Results (mobile)

This parameter specifies whether mobile results without a name should display as a geographic value or as wireless. Configure using the parameter "mobile" and one of the values "location" or "wireless". For example, these are all valid requests with a specified mobile:

https://api.opencnam.com/v3/phone/+16786318356?format=json&casing=caps&mobile=wireless
https://api.opencnam.com/v3/phone/+16786318356?format=json&mobile=location
https://api.opencnam.com/v3/phone/+16786318356?mobile=location

No Value (no_value)

This parameter specifies whether results without a value should display as "UNKNOWN" or a blank response. Configure using the parameter "no_value" and one of the values "unknown" or "blank". For example, these are all valid requests with a specified no_value:

https://api.opencnam.com/v3/phone/+16786318356?format=json&no_value=caps&no_value=blank
https://api.opencnam.com/v3/phone/+16786318356?format=json&mobile=location&no_value=unknown
https://api.opencnam.com/v3/phone/+16786318356?no_value=blank

Geographic Resolution (geo)

This parameter specifies whether results with a geographic location value are derived from the wire center or rate center. Configure using the parameter "geo" and one of the values "wire" or "rate". For example, these are all valid requests with a specified geo:

https://api.opencnam.com/v3/phone/+16786318356?format=json&no_value=caps&geo=wire
https://api.opencnam.com/v3/phone/+16786318356?format=json&mobile=location&geo=rate
https://api.opencnam.com/v3/phone/+16786318356?geo=wire



Authentication

All OpenCNAM requests require authentication, either using the Authorization header, by passing your account_sid and auth_token as query string parameters, or by using IP authentication. Using the Authorization header is recommended because it is standard, often simplifies coding, and helps keep credentials out of your logs.

Query String: account_sid and auth_token

You may authenticate by passing the account_sid and auth_token in the query string. Below you will find an example of authentication using the the account_sid and auth_token parameters within the query string. To keep credentials out of your logs, we recommend using the Authorization header for authentication instead. See the next section for details.

curl 'https://api.opencnam.com/v3/phone/+16786318356?account_sid=SID&auth_token=TOKEN'

Authorization Header

You may authenticate using HTTP Basic authentication, using your SID and TOKEN as the username and password. In short, this adds the Authorization header to the HTTP request with a value of Basic CREDENTIALS where CREDENTIALS is the base-64 encoding of SID:TOKEN your SID and TOKEN with a colon in between.

In pseudo-code, it's like this:

auth_header = "Authorization: Basic " + base64_encode(SID + ":" + TOKEN)
cnam = http_get("https://api.opencnam.com/v3/phone/+16786318356", headers=[auth_header])
print(cnam)
> TELO

With curl Authorization headers are not required:

curl --user SID:TOKEN https://api.opencnam.com/v3/phone/+16786318356

IP Authentication (Advanced Authentication Option)

OpenCNAM supports IP authentication. You may login to your customer control panel and enable this feature by clicking on the 'Show IP Authentication Options' link under Manage Account. Once added, valid requests made from these whitelisted IP address will be processed and debited from your account, and will not require your SID and Auth Token for authentication.



Passthrough Data

If youre looking to add more customized data to your API response, we have passthrough data available. You may add up to ten passthrough entries that will appear in the JSON output. (Be sure to request JSON output if you want to see passthrough data.) The values that are passed through using these parameters are also available in the Detailed Reports that may be downloaded by visiting the Analytics section in your control panel.

$ curl 'https://api.opencnam.com/v3/phone/+16786318356&format=json&passthrough=REQ-35934&passthrough=SYS-ZYXSD'
{
    "name": "TELO",
    "number": "+16786318356",
    "uri": "/v3/phone/+16786318356",
    "price": -0.0039
    "passthrough": [
      "REQ-35934",
      "SYS-ZYXSD"
    ]
}



Response Formats

To specify a response format, pass the desired Accept header or format query string parameter.

Text (default)

Only output the CNAM response using the header Accept: text/plain or query string format=text.

$ curl https://api.opencnam.com/v3/phone/+16786318356
$ curl -H 'Accept: text/plain' https://api.opencnam.com/v3/phone/+16786318356
$ curl 'https://api.opencnam.com/v3/phone/+16786318356?format=text&account_sid=SID&auth_token=TOKEN'
TELO

JSON

Only output the CNAM result along with some metadata in JSON format using the header Accept: application/json or query string format=json.

$ curl -H 'Accept: application/json' https://api.opencnam.com/v3/phone/+16786318356
$ curl 'https://api.opencnam.com/v3/phone/+16786318356?format=json'
{
    "name": "TELO",
    "number": "+16786318356",
    "uri": "/v3/phone/+16786318356",
    "price": -0.0039
}

JSONP

Wrap the JSON result in a JavaScript callback using the header Accept: application/javascript or query string format=jsonp. You may also specify the callback function by passing a callback, which defaults to callback. For security, the callback is restricted to a letter (a-z or A-Z), underscore, or $ followed by alphanumeric characters (a-z, a-Z, 0-9). The following are equivalent:

$ curl -H 'Accept: application/javascript' https://api.opencnam.com/v3/phone/+16786318356
$ curl 'https://api.opencnam.com/v3/phone/+16786318356?format=jsonp'
$ curl 'https://api.opencnam.com/v3/phone/+16786318356?format=jsonp&callback=callback'
callback({
    "name": "TELO",
    "number": "+16786318356",
    "uri": "/v3/phone/+16786318356",
    "price": -0.0039
});



Status Codes and Errors

When making OpenCNAM requests, there are several different HTTP status codes you may receive. If the status code is 200, everything went well. All other status codes indicate an error in processing the request.

200 OK

The request was successful.

400 BAD REQUEST

The phone number or an argument (e.g. format) isn't valid.

401 UNAUTHORIZED

The request was missing authentication or the credentials are not valid.

402 PAYMENT REQUIRED

Authentication succeeded, but the account does not have enough funds available to complete the request.

404 NOT FOUND

The phone number doesn't have any CNAM information available.



Support

Our team can be reached in any of the following ways:

Phone: +1-888-315-8356 (TELO) or +1-678-631-8356 (TELO)
Email: support@opencnam.com

Ready to integrate OpenCNAM?

GET STARTED Try it free! No card required.