Facebook tracking pixel
Integration Guides


In a hurry to get started? Or maybe you're an API-pro? This should get you going:

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

Note that insecure HTTP requests are both supported and not-recommended. It is provided for legacy support, but be aware that your credentials, query parameters, and response data will all be susceptible to sniffing.

To test the API without incurring charges, please use the following demo number: +15551234567

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

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


This documentation uses a couple notes and documentation conventions that are worth pointing out.

  • 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 +. While OpenCNAM will certainly try to figure out what you meant 10-digit NANP numbers will work without a +1 it's best to just supply the full number. (For example for NUMBER use +16786318356 instead of 6786318356 or 678-631-8356.)
  • This documentation uses curl gratuitously. If you don't already know curl, you're about to become great friends. Note that many shells (e.g. bash) give special meaning to ?, &, and other characters, so you'll need to single-quote your URLs as in the examples below.

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.

Service Level Override (service_level)

You can configure your service level on a per request basis with the query parameter "service_level" and one of the values "standard" or "plus". For example, these are all valid requests with a specified service level:


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:


Mobile Results (mobile)

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


No Value (no_value)

Specifies whether results without a value should display as unknown or a blank. Configure using the query-string "no_value" and one of the values "unknown" or "blank". For example, these are all valid requests with a specified no_value:


Geographic Resolution (geo)

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



All OpenCNAM requests require authentication, either using the Authorization header or by passing your account_sid and auth_token as query string parameters. 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. To keep credentials out of your logs, we recommend using the Authorization header for authentication instead. See above 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])

And, of course, curl handles it without issue:

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 'Advanced 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 do not require your SID and Auth Token for authentication.

Response Formats

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

Text (default)

Output only 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'


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


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'
    "name": "TELO",
    "number": "+16786318356",
    "uri": "/v3/phone/+16786318356",
    "price": -0.0039

Passthrough Data

Need to add some custom data to your API responses? We've got you covered with passthrough data. 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.)

$ 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": [

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.


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


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


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


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

Ready to integrate OpenCNAM?

GET STARTED Try it free! No card required.