CallerID Get (3rd Party CID Fetch)

Instead of using the national callerID database, we can fetch a caller's callerID information from a 3rd-party system or CRM software, as long as they implement the appropriate API on their side.

Configuration Settings

You can configure CallerID Fetch on a per-phone-number basis. In the Admin Portal, go to Call Routing > Inbound, then edit a phone number. The following fields exist:

• CallerID GET URL
  • Required 
  • This is the URL of the 3rd-party CRM or database software that our system will use to make a GET request for callerID. For an example of our request syntax, see the next section.
• CallerID GET X-API-Key
  • Optional
  • When we make the GET request, we can include an X-API-Key header with your custom value if authentication is required.
• CallerID GET JSON Field
  • Required
  • The 3rd party API's response should be in JSON, with a single Key-Value pair. The "Field" is the name of the Key. For an example of the expected response, see the next section.
• CallerID GET Validated Prefix
  • Optional
  • If the call is successful, and a JSON response is returned with the Field defined, we can prefix the callerID on the customer's phone system going forward. You might want to put "[V] " in front of the CallerID, to signify the caller is "verified" or maybe you add "Cust-" to it to indicate the caller is a real customer to a call center agent.

Example of Our GET Request

The syntax of our request is {your_callerid_get_url}?phoneNumber={CALLER'S_NUMBER} with an example of this below:

https://crm.provider.com/callerid_lookup?phoneNumber=19726001150

Where "https://crm.provider.com/callerid_lookup" is the "CallerID Get URL" field you configure in the Admin portal.

If you have X-API-Key set, we will send it along in the GET headers.

Example of Your JSON Response

{"field":"callerID text to display"}

Any other response will be treated as a failure, and the phone system will simply continue using the national database for lookup.

API Timeout & Caller Silence

As of this writing, the phone system will wait up to 6 seconds for your API to respond. This causes the caller to hear silence during your API's response. Please attempt to respond as quickly as possible to encourage a good caller experience.

Live Test Case

If you would like to test this feature out, you can set the following parameters:

CallerID Get URL: https://voice.getkontak.com/api/test_callerid_get.php

CallerID Get JSON Field: callerid_text

If you visit the URL above in your browser, you'll see that the output is a JSON block containing "HELLO X" where X is the phoneNumber parameter passed when a call comes in.