Call Us Today! 877.742.2583

Page tree
Skip to end of metadata
Go to start of metadata


mod_cidlookup is a Caller*ID lookup API. This FreeSWITCH module allows one to:

  • lookup a number to name mapping in a local database
  • lookup a number to name mapping from a URL
  • cache the results of the URL lookup in memcache (if the cache module is installed)
  • if all else fails, lookup city and state information


 Click here to expand ToC


caller_id_number and caller_id_name are set by FreeSWITCH core. Users should set the channel variable effective_caller_id_name.

The API can be called via ESL or used directly from fs_cli.

cidlookup status|number [skipurl] [skipcitystate]


mod_cidlookup only requires the modules that support your selected lookup methods. If any of the supporting modules are missing (mod_curl, local database, mod_memcache) that part of the functionality will be disabled. memcache support requires the mod_memcache module to be loaded.


To use mod_cidlookup:

Tell FreeSWITCH to compile in this module by editing modules.conf in /usr/src/freeswitch/trunk and uncomment the following line:


Now recompile FreeSWITCH:

linux command line

Now tell FreeSWITCH to load cidlookup and supporting modules by adding to or uncommenting their entries in modules.conf.xml in $FS_ROOT/conf/autoload_configs:


Finally, edit the default config in the autoload_configs directory to hold your cidlookup configuration.

Now start FreeSWITCH and test.

CallerID / CNAM Database Resources lists number-to-name database providers.

Some CNAM providers offer a way to perform the CNAM DIP via an e164 method or a SIP Subscribe method.

For information on how to perform the CNAM dip via e164, or ENUM see this page on Enum / e164 VoIP CNAM Dips.

There is no obvious way to perform the CNAM DIP via the SIP Subscribe method, although that does not mean that it isn't possible.


Sometimes the retrieval of information from certain online providers takes an appreciable time to occur. If you perform the CID lookup before you perform the <action application="answer"/> in your dialplan, the originating carrier might time out and drop the call or behave in unexpected ways.

If you wish to perform the CID Lookup before answering the call in order to take action not only on numbers, but also on names, use <action application="pre_answer"/> before performing the CID lookup. This solves the problem of the carrier giving up on the call, amongst other problems.



url - Uniform Resource Locator of the service that takes a properly formatted telephone number and returns as its only data the name. There are several online providers that do this or you can implement this yourself. The sample config uses the service from OpenCNAM.

whitepages-apikey - offers a free reverse lookup API for low volume use. If you intend to run a high volume of queries, they offer a commercial service. Refer to for an API key.

cache - Set to true or false. Use memcache to cache the number-to-name lookup

cache-expire - Number of seconds to keep the lookup in the cache.

odbc-dsn - database:user:password The ODBC database connection string

sql - The SQL query to execute. The only parameter supported is ${caller_id_number} which is translated to the number passed to cidlookup. The query should return a single value which is the name.

citystate-sql - The SQL query to execute when falling back to city, state query. The only parameter supplied is ${caller_id_number} which is the number passed to cidlookup. The query should return a single value which is the name of the city, state. This is ONLY used for NANPA numbers. They must be 11 digits and start with 1.


If memcache is enabled, the cache will be checked first before performing other lookups. However, only the results of successful URL lookups are cached. Lookups from the "City, State" fallback are not cached.

Sample configuration file

Sample cidlookup configuration  Expand source
Trivial sample configuration  Expand source

Sample SQL Schema - PostgresSQL (not sqlite)

Create sample SQL schema
Sample schema for PostgreSQL  Expand source



To verify that mod_cidlookup is functioning correctly and using the options from your config file, type this in fs_cli:


To test a sample lookup, invoke cidlookup with a properly formatted telephone number:


If you have DEBUG logging turned on, you'll see it trying each step and, if you're using the cache module, whether the data is stored in memcache or not.

This verifies that the module is running and it can load its configuration information.


The cidlookup application sets the channel variable caller_id_name if the lookup succeeds. The easiest way to use it is to put the following block towards the top of your dialplan/public.xml

Dialplan example  Expand source


Easier Dialplan

The documentation isn't quite clear that what we're really trying to set here is effective_caller_id_name (vs caller_id_name). For an inbound route it would look something like this:

 Expand source



This will cause a lookup if the call comes from "Anonymous" too, but perform an SQL lookup of "blank" (it strips alpha characters it seems) which will return unrelated results. This example should be not be used in production systems.

A failed lookup will result in a value of "-ERR" -- check for that value prior to setting effective_caller_id_name.

Fallback to "City, State"

If the name lookup fails or if you wish only to provide the general location of the number based on telco records, an additional database can be utilized. The table needs to be loaded into the same database as your cidlookup directory database. One source is the CSV file available at: npa nxx file

One way to load this data into PostgreSQL is with the following DDL

PostgreSQL DDL  Expand source

You can then load the data using psql with

psql  Expand source


The default config will work with the above data structure.

Setting Outbound Name

Some phones, including Polycom and Snom, support setting the callee's name once the call is complete. This allows the caller to see the name of the person being called as well as the number. Using cidlookup the name could come out of your corporate directory and if that doesn't work will be queried against a CNAM lookup service. Assuming you've already normalized your number to E.164 (without the leading +), just add the following to your dialplan prior to the bridge:

Callee Dialplan XML


Using OpenCNAM

OpenCNAM ( is a large CNAM provider that works well with FreeSWITCH. OpenCNAM provides two tiers of CNAM lookups:

  • A Hobbyist tier, which allows you to lookup a maximum of 60 cached CNAM queries per hour, completely free
  • A Professional tier, which allows unlimited real-time CNAM queries, for a fee ($0.004 per successful lookup at the time of this writing)

To get started with OpenCNAM's Hobbyist tier, you don't need to do anything. OpenCNAM's Hobbyist tier doesn't require any registration or accounts and is enabled by default in the cidlookup.conf.xml configuration file.

If you need to query more than 60 requests per hour, or prefer to have more accurate Caller ID information (with real-time CNAM queries), you can create an OpenCNAM account on their website, deposit funds into your account, then update your cidlookup.conf.xml configuration file appropriately. Once you've created an OpenCNAM account, you'll notice that on your dashboard page you have two account tokens at the top of your page: an Account SID and Auth Token. To make FreeSWITCH use OpenCNAM's Professional tier and thereby perform only real-time CNAM queries, modify your cidlookup.conf.xml file's URL attribute thus:

OpenCNAM Professional config  Expand source


Using PHP

If you run also a webserver and have PHP on it you can query web directories for the caller id. The following example uses to look up Swiss phone numbers. They offer an API with XML output from which the name will be parsed. To use their API you have to get the key. In this case you can get the key from here:

Prerequisite is the php5-curl library that must be installed on your server. Adjust this as required.

PHP web server config  Expand source


Save that script somewhere on your server and enhance the freeswitch/conf/autoload_configs/cidlookup.conf.xml with this



The above example assumes that you named the PHP script index.php and that it resides in the /cid/ folder from the server.

Background CID Lookups

A CID lookup can introduce a delay of several seconds, depending on which service you use. If you answer with an IVR, the CID lookup can happen in the background, while the IVR is playing the greeting.

To do this, first create the following Lua script:

cid_bg.lua  Expand source

Next, call the script from the "public" dialplan as follows:

Dialplan context public  Expand source


  1. Anonymous

    I would log in but I can't.  I can't send the administrators email either, so I have to remain anonymous.  I'm wondering how FS would know that the output from the above mentioned PHP script (echo statement) should be assigned to the effective_caller_id?  I don't see the connection.

    1. I guess you would call the PHP script on your web server with curl or equivalent. Assign that result to the variable of your choosing. I think the http request and variable assignment can all be done in one line, at least I've seen it expressed that way.

      The freeswitch-users mailing list is a better place to ask questions as MANY more eyes will see it and can answer your question for sure.