CallerID Get (3rd Party CID Fetch)

CallerID Get (3rd Party CID Fetch)

Overview


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 proper 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, where our system will perform a GET request for callerID. For an example of our request syntax, see the next section.

  • CallerID GET X-API-Key
    • Optional
    • When we perform the GET request, we can send along an X-API-Key header, with your custom value, in case some authentication is necessary.

  • 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.
 

Request Examples


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:
 
 
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 the time 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 return a response as quickly as possible, to encourage 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://pbx.primevox.net/api/test_callerid_get.php
CallerID Get JSON Field: callerid_text
 
If you visit the above URL in your browser, you'll see the output will be a JSON block with "HELLO X" where X is the phoneNumber parameter passed when a call comes in.

    • Related Articles

    • Understanding Caller ID

      How is Caller ID Determined? Caller ID is updated by telephone service providers and maintained by third-party CNAM (Calling NAMe) database providers. Unfortunately, there is no standard or governing body regulating these CNAM providers, so Caller ID ...

    • Call History / CDR (V2)

      Getting a List of Calls (Call Summary API) REQUEST: GET http://pbx.primevox.net/api/call_list.php?auth=API_KEY&containerID=CCCCCC&tenantID=TTT&{extra filter parameters, see below} NOTE: All parameters are Case Sensitive. auth (API_KEY) is your API ...

    • SMS/MMS Messaging (V2)

      Fetching SMS/MMS Conversation List REQUEST: GET https://pbx.primevox.net/api/messaging/v1/conversations URL PARAMS: All parameters are Case Sensitive. auth is the string of text in the phone system's Advanced menu. It looks like a lot of nonsense. ...

    • Purchasing and Managing Phone Numbers in Qvara (Purple) Portal

      Introduction Higher-level users have the ability to purchase phone numbers directly from the platform. Purchasing phone numbers allows you to assign local, toll-free, or international numbers to your account(s) for use with extensions, call flows, or ...

    • Webhooks

      What is a Webhook? A webhook allows your phone system to send real-time data or notifications to an external application (usually your own server or a third-party platform). It acts as a trigger: when a specific event occurs—such as an incoming call, ...