Facebook tracking pixel

DOCS

Quickstart

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.



Basics

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 +12128675309 instead of 2128675309 or 212-867-5309.)
  • 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:

https://api.opencnam.com/v3/phone/+16284003994?format=json&service_level=standard
https://api.opencnam.com/v3/phone/+16284003994?format=json&service_level=plus
https://api.opencnam.com/v3/phone/+16284003994?service_level=standard
https://api.opencnam.com/v3/phone/+16284003994?service_level=plus

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/+16284003994?format=json&service_level=standard&casing=caps
https://api.opencnam.com/v3/phone/+16284003994?format=json&casing=title
https://api.opencnam.com/v3/phone/+16284003994?casing=caps

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:

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

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:

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

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:

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



Authentication

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/+16284003994?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/+16284003994", headers=[auth_header])
print(cnam)
> TELO

And, of course, curl handles it without issue:

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

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/+16284003994
$ curl -H 'Accept: text/plain' https://api.opencnam.com/v3/phone/+16284003994
$ curl 'https://api.opencnam.com/v3/phone/+16284003994?format=text&account_sid=SID&auth_token=TOKEN'
TELO

JSON

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/+16284003994
$ curl 'https://api.opencnam.com/v3/phone/+16284003994?format=json'
{
    "name": "TELO",
    "number": "+16284003994",
    "uri": "/v3/phone/+16284003994",
    "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/+16284003994
$ curl 'https://api.opencnam.com/v3/phone/+16284003994?format=jsonp'
$ curl 'https://api.opencnam.com/v3/phone/+16284003994?format=jsonp&callback=callback'
callback({
    "name": "TELO",
    "number": "+16284003994",
    "uri": "/v3/phone/+16284003994",
    "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/+16284003994&format=json&passthrough=REQ-35934&passthrough=SYS-ZYXSD'
{
    "name": "TELO",
    "number": "+16284003994",
    "uri": "/v3/phone/+16284003994",
    "price": -0.0039
    "passthrough": [
      "REQ-35934",
      "SYS-ZYXSD"
    ]
}



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.



Client Libraries

While the OpenCNAM API is extremely simple, there are several open-source libraries that you can use to make integration even easier. This section lists various unofficial client libraries and samples for getting started with each.

Writing your own OpenCNAM library? We'd love to list it! Please send us an email and tell us about it!

Android

iOS

node.js

Python

Ruby

.NET

The Caller ID product is advanced. Everything else is simple.

START USING OPENCNAM Try it free! No card required.