EZCNAM API DOCUMENT

THE API CALL

The EZCNAM API call is an HTTPS query consisting of 4 simple parts:
EZCNAM HTTPS query
  • API web address - The HTTP address of our API servers.
  • Key - Your unique API key will be assigned to you when you create an EZCNAM account.
  • Phone Number - The phone number you would like to look-up.
  • Format - You can get your CNAM result in any of these formats: json, xml, text


EXAMPLES

Try these examples, but don't forget to replace the x's with your actual account key:

JSON Query: https://api.ezcnam.com/v1?key=xxxxxxx&phone=12125551234&out=json

JSON response: {"status":"OK","name":"Singh Daniel"}


XML Query: https://api.ezcnam.com/v1?key=xxxxxxx&phone=12125551234&out=xml

XML Response:
<result>
     <status>OK</status>
     <name>Singh Daniel</name>
</result>


Text Query: https://api.ezcnam.com/v1?key=xxxxxxx&phone=12125551234&out=text

Text Response: Singh Daniel

TESTING

Since the EZCNAM API is actually just a regular URL, the easiest place to test an API call is in your web browser on your computer. Simply paste the API call into the address bar of your browser and press enter. This will allow you to view exactly what is being returned from your API call. Try it with the examples above!


NEW! International CNAM Support

Parameter: cc (Country dialing Code)

Expand your CNAM lookups beyond North America by specifying the country dialing code:

  • Omit cc or set &cc=1 - Default USA/Canada behavior (backward compatible)
    Example: phone=8185551234 automatically becomes 18185551234

  • Set &cc=<country_code> - Target specific country
    Example: cc=44&phone=2071234567 treats number as UK
    Example: cc=44&phone=442071234567 works identically (country dialing code detected and not duplicated)

  • Set &cc=ALL - Auto-detect the country from the phone number
    Requires country code in phone number: cc=ALL&phone=442071234567
    Accepts various formats: +44207, 442071234567, etc.
    Will fail if country code missing: cc=ALL&phone=2071234567 ❌

Put simply, if all of the phone numbers you send us will be from the same country, set cc to the dialing code for that country. If you're going to be sending us phone numbers from different countries, set &cc=ALL, and make sure each phone number you send us has the dialing code prepended to the phone number.


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 - Specifies all-uppercase (&case=U), all lowercase (&case=L), or mixed case (&case=M)
  • &score - Returns fraud score from 0-100. Higher values indicate higher chance of call being fraudulent
  • &update - Allows you to update a CNAM value for your organization. Must be used WITHOUT the "phone" parameter and WITH the "value" parameter.
          Usage: &update=XXXXX&value=YYYYY, where XXXXX is the phone number and YYYYY is the desired CNAM value


    • CODE EXAMPLES

    Here are some examples in various programming languages:

    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']