Your choice for CNAM is EZ.  Contact Us

[email protected]
Phone: +1 (844) 597-2626
EZCNAM Logo
Sign Up
Documentation

API Documentation

Reverse phone number lookups via a simple HTTPS request.
Returns caller name (CNAM) in JSON, XML, or plain text.
01 The API Call

Every API call is a single HTTPS URL built from four simple parts:

https://api.ezcnam.com/v1?key=xxxxxxx&phone=12125551234&out=json
API Endpoint Base HTTPS address for all requests
key= Your unique account API key
phone= The phone number to look up
out= Response format: json, xml, or text
02 Examples

Replace xxxxxxx with your actual API key in all examples below.

Query URL
https://api.ezcnam.com/v1?key=xxxxxxx&phone=12125551234&out=json
Response
{ "status": "OK", "name": "Singh Daniel" }
Query URL
https://api.ezcnam.com/v1?key=xxxxxxx&phone=12125551234&out=xml
Response
<result> <status>OK</status> <name>Singh Daniel</name> </result>
Query URL
https://api.ezcnam.com/v1?key=xxxxxxx&phone=12125551234&out=text
Response
Singh Daniel
03 Testing
🌐

Test directly in your browser. Since every API call is a plain HTTPS URL, just paste one into your browser's address bar and press Enter. This will allow you to view exactly what is being returned from your API call. Try any of the example URLs above — swap in your API key first.

04 International CNAM
New

International Support

cc=

Extend CNAM lookups beyond North America using the &cc= parameter with the country's dialing code.

Omit or cc=1 Default — USA & Canada
ex phone=8185551234 → treated as 18185551234
cc=<country_code> Target a specific country
ex cc=44&phone=2071234567 → treats number as UK
ex cc=44&phone=442071234567 → also works (dialing code not duplicated)
cc=ALL Auto-detect country from number
ex cc=ALL&phone=442071234567 ✓
ex cc=ALL&phone=+442071234567 ✓
fail cc=ALL&phone=2071234567 ✗ — country code required
Rule of thumb: If all your lookups are from one country, set cc to that country's dialing code. If you're mixing countries, use cc=ALL and always include the dialing code in the phone number.
05 Optional Parameters
&names_only
Only returns subscriber names or blanks; won't return city and state, Wireless Caller, etc.
&test_mode
Returns random 80's R&B artist names instead of CNAM - no charge per query
&case=
Control name casing: U = ALL CAPS  ·  L = all lowercase  ·  M = Mixed Case
&score
Appends a fraud score from 0–100. Higher values indicate a higher probability of the call being fraudulent.
&update
Update a CNAM value for your organization. Use without phone= and with value=.
Usage: &update=PHONE_NUMBER&value=NEW_CNAM
06 Code Examples
cURL
curl "https://api.ezcnam.com/v1?key=xxxxxx&phone=2125551234&out=json"
PHP
<?php $url = "https://api.ezcnam.com/v1?key=xxxxxx&phone=2125551234&out=json"; $ret = file_get_contents($url); $result = json_decode($ret); echo $result->name; ?>
Perl
use LWP::UserAgent; use JSON; $url = "https://api.ezcnam.com/v1?key=xxxxxxx&phone=2125551234&out=json"; $ua = LWP::UserAgent->new(ssl_opts => { verify_hostname => 1 }); $res = $ua->get($url); $json = decode_json($res->decoded_content); print $json->{'name'}; # Note: Socket_SSL and JSON libraries must be installed. # CentOS Linux example:: # yum install -y perl-IO-Socket-SSL perl-JSON.noarch
Python
import json import urllib2 url = "https://api.ezcnam.com/v1?key=xxxxxx&phone=2125551234&out=json" res = json.load(urllib2.urlopen(url)) print res['name']