Skip to main content

REST API Contact Resolution

Overview​

Connect any external REST API to resolve caller identity in real-time. When a call arrives, Call Telemetry sends the caller's phone number to your API endpoint and uses the response to display the caller's name on Cisco IP phones. This works with any system that exposes a REST/JSON API -- ServiceNow, Salesforce, custom CRM systems, or internal databases.

For a step-by-step walkthrough using a sample webhook app, see the Webhook CRM Integration guide.

Requirements​

Configuration​

Create a Webhook App​

  1. Navigate to Realtime Policies → Apps
  2. Click Add → Select External API Contact Resolution under the Realtime tab
Screenshot of the Create New Application dialog with External API Contact Resolution highlighted
  1. Configure the webhook:
    • Name -- Descriptive name (e.g., "ServiceNow Caller Lookup")
    • URL -- Your API endpoint URL. Use {event.calling_number} as a template variable for the caller's phone number.
    • HTTP Method -- GET or POST depending on your API
    • Headers -- Add authentication headers if required (e.g., Authorization: Bearer <token>)
  2. Save the app
Screenshot of the External API Contact Resolution app configuration with endpoint, authentication, field mapping, caching, and sync settings

Associate with a Policy Rule​

  1. Navigate to Policies and open your call policy
  2. Select the rule that handles incoming calls
  3. Click Associate App and select your webhook
  4. Save the rule

The webhook now executes for every call that matches the rule's trigger pattern.

Template Variables​

Use these variables in the API URL and request body to pass call data to your API:

VariableDescription
{event.calling_number}The caller's phone number
{event.called_number}The number that was dialed
{event.calling_device}The calling device name

Variables are replaced with actual values at runtime before the API request is sent.

Response Mapping​

The API response is available in the rule configuration under app_data.webhook.data. Use dot notation to reference nested fields from your API response:

Template PathDescription
{app_data.webhook.data.name}Caller name from API response
{app_data.webhook.data.company}Company name from API response
{app_data.webhook.data.account_id}Account identifier from API response

To display the resolved name on Cisco IP phones, map the caller name field to Calling Party Name in your rule's modifiers section.

Example API Request​

GET https://api.yourcrm.com/contacts?phone={event.calling_number}

Example Response:

{
  "name": "Jane Smith",
  "company": "ACME Corp",
  "account_id": "ACC-12345"
}

In this example, set the Calling Party Name modifier to {app_data.webhook.data.name}. The phone display shows "Jane Smith" instead of the raw phone number.

Testing Your Integration​

Use Call Tests to verify your API integration before routing live calls:

  1. Navigate to Policies → Call Test
  2. Enter a test calling number that exists in your CRM
  3. Run the test
  4. Check app_data.webhook.data in the results for your API response
  5. Verify the Calling Party Name in the CURRI response shows the resolved name

If the test returns the correct name, your integration is working. Live calls through the same policy rule display the resolved name on Cisco IP phones.

Troubleshooting​

No data returned? Use the Test Connection button in the app settings to verify the endpoint is reachable. Check the API URL and authentication configuration.

Authentication errors? Verify the authentication type and credentials match what your API expects. Use the Custom Headers section if your API requires non-standard headers.

Wrong name displayed? Check the API Response Field Mapping — make sure the JSON field names match your API's response structure (e.g., name, company, email).

Connection test passes but calls don't resolve? Verify the app is assigned to a policy rule under the Apps tab. The app only runs for calls that match the rule's trigger pattern.

Last updated on by Call Telemetry