Asterisk, FreePBX, VitalPBX and Issabel: caller ID lookup via HTTP
Asterisk sets the caller name in the dial plan. You decide where the name comes from: an HTTP lookup per call that returns it from your CRM, database or directory.
How Asterisk looks up a name
- Asterisk directly: in the incoming context, the function
CURL(modulefunc_curl) calls an address; the result is written toCALLERID(name)before the phone rings. - FreePBX and Issabel: the module CallerID Lookup Sources takes an HTTP source with host, port, path and query. Details are in the Sangoma documentation.
- VitalPBX: a CID lookup source (HTTP/HTTPS) in the inbound route.
Keep the time-out short: if the service does not answer, the call should still ring at once. With HTTPS, Asterisk must trust the certificate of the service (store the root certificate on the Asterisk server).
With CallerHub: the address for your phone system
In CallerHub, create an interface for your phone system under Interfaces → Add interface, enter the address of the Asterisk server under Allowed IP addresses and choose Save and apply. “Copy instructions” provides the complete address with the real API key. The examples use 192.168.10.5 as the CallerHub computer and the placeholder API-KEY.
| Phone system | Query to enter |
|---|---|
| Asterisk / FreePBX (dial plan) | …/lookup?apikey=…&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})} |
| FreePBX / Issabel (CallerID Lookup Sources) | path /lookup, query format=text&apikey=…&number=[NUMBER] |
| VitalPBX (CID lookup source) | …/lookup?apikey=…&number=[CIDNUM] |
Dial plan example (FreePBX: extensions_custom.conf, context from-pstn-custom or similar)
exten => _X.,1,Set(CURLOPT(httptimeout)=2)
same => n,Set(CALLERID(name)=${CURL(http://192.168.10.5:8080/lookup?apikey=API-KEY&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})})})
same => n,Goto(from-pstn,${EXTEN},1)
Then reload the dial plan (dialplan reload). If CallerHub cannot be reached, the name stays empty after 2 seconds and the call continues normally. called passes the called number on for the statistics.
Call analytics via AMI or Master.csv
For answer rate and service level, the callback list and the live view, CallerHub reads the call records:
- Live via AMI: CallerHub connects to port 5038. Create a user with
read = cdrinmanager.confand setenabled = yesincdr_manager.conf. - File:
Master.csvfrom the Asterisk CDR module, also for past calls.

Common errors
| Observation | Cause and remedy |
|---|---|
| Name stays empty, CallerHub shows no request | The request does not reach CallerHub: check address, port, Windows firewall and firewalls between the networks; test from the Asterisk server with curl. Is func_curl loaded? |
Log: status=401 or 403 | Wrong API key, or the address of the Asterisk server is not among the allowed IP addresses. Behind NAT the sender differs. |
| Request arrives, but no name | Number unknown (test with “Check number”), wrong format, or the time-out is shorter than the response time. |
| Umlauts or accents wrong | Responses are UTF-8; check the character set of the phone system. |
The guides for Asterisk, FreePBX, VitalPBX and Issabel are based on published interfaces and have not yet been checked with these systems. Check placeholders, menu paths and setting names against the documentation of your version.
Frequently asked questions
Which response format does Asterisk expect?
Plain text: just the name, empty for unknown numbers. This is the CallerHub default for Asterisk, FreePBX, VitalPBX and Issabel; with format you can also choose JSON or XML.
Does the lookup slow down the call?
CallerHub answers calls from the phone number list in memory, so a slow database does not delay the response. The time-out in the dial plan also limits the wait, to 2 seconds in the example.
Can I connect several Asterisk servers?
Yes. Each phone system gets its own interface with its own API key, its own allowed IP addresses and its own selection of data sources. The basic edition allows one interface, the full edition up to ten.
Test it with your own data.
Try the full edition for 30 days: choose “Request trial …” in CallerHub and the trial key arrives by e-mail. The setup wizard guides you through data source, phone system and test lookup. After that, CallerHub continues as the free basic edition without losing settings or data.