Skip to main content
GET
Find Call by Attribute

Overview

Use this endpoint to reconnect your application’s identifiers with the corresponding call. See the AI phone calls guide for more about call data. This endpoint allows you to find a call by searching for specific attributes in either the call’s params or external_identifiers fields. It returns the most recent call that matches your search criteria.

Search Options

You must provide at least one of the following search criteria:

Search by Parameters

  • param_key + param_value: Search for a call where the params field contains the specified key-value pair

Search by External Identifiers

  • external_identifier_key + external_identifier_value: Search for a call where the external_identifiers field contains the specified key-value pair

Example Use Cases

  1. Find a call by customer ID:
  2. Find a call by appointment type:
  3. Return only fields needed by an IVR or reporting integration:

Compact responses

Use the optional fields parameter to return only the data your integration needs, with a maximum of 50 fields. Supported call fields are id, summary, status, duration, transferred, agent_id, and agent_commit_id. Select an individual call parameter with params.<key>. For example, fields=id,summary,status,params.disposition returns:
Missing requested parameter keys are returned as null. Unsupported fields return a validation error. When fields is omitted, the endpoint returns the complete call details for backward compatibility.

Response

Returns a CallFindByAttributeResponse object containing:
  • success: Boolean indicating if a call was found
  • call: The requested compact fields, or the full call details when fields is omitted

Notes

  • Only returns the most recent call matching the criteria
  • Searches are case-sensitive
  • Returns 404 if no matching call is found
  • Returns 422 if no search criteria are provided

Authorizations

Authorization
string
header
required

Query Parameters

param_key
string

The key to search for in the call's params field

param_value
string

The value to match for the specified param_key

external_identifier_key
string

The key to search for in the call's external_identifiers field

external_identifier_value
string

The value to match for the specified external_identifier_key

fields
string

Comma-separated fields to return, with a maximum of 50 fields. Supported call fields are id, summary, status, duration, transferred, agent_id, and agent_commit_id. Select individual call parameters with params.. The full call is returned when omitted.

Maximum string length: 1000
Example:

"id,summary,status,params.disposition"

Response

Successful Response

success
boolean
required

Indicates if the request was successful

call
CallDetailsResponse · object
required

The full call details when fields is omitted, or only the requested fields when fields is provided

Last modified on September 3, 2026