Find Call by Attribute
curl --request GET \
--url https://api.usesimple.ai/api/v1/calls/find_by_attribute \
--header 'Authorization: <api-key>'import requests
url = "https://api.usesimple.ai/api/v1/calls/find_by_attribute"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://api.usesimple.ai/api/v1/calls/find_by_attribute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usesimple.ai/api/v1/calls/find_by_attribute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usesimple.ai/api/v1/calls/find_by_attribute"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.usesimple.ai/api/v1/calls/find_by_attribute")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usesimple.ai/api/v1/calls/find_by_attribute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"call": {
"id": 123,
"simple_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"from_number": "<string>",
"to_number": "<string>",
"status": "<string>",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"duration": 123,
"created_at": "2023-11-07T05:31:56Z",
"prompt": {
"prompt_text": "<string>",
"created_at": "2023-11-07T05:31:56Z"
},
"transcripts": [
{
"text": "<string>",
"role": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"function_name": "<string>",
"arguments": {}
}
],
"call_prompt": "<string>",
"answered_by": "voicemail",
"record": true,
"language": "en",
"transferred": true,
"handoff_metadata": {
"five9": {
"conversation_id": "<string>",
"tenant_name": "<string>",
"campaign_name": "<string>",
"transferred_at": "2023-11-07T05:31:56Z"
}
},
"direction": "<string>",
"tags": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"description": "<string>",
"color": "<string>"
}
],
"voice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"background_noise": "<string>",
"agent_speaks_first": true,
"agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_branch": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_commit_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_branch_name": "<string>",
"external_identifiers": {},
"params": {},
"recording_presigned_url": "<string>",
"analyzers": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {
"type": "string",
"properties": {}
}
}
],
"analysis_results": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"analyzer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {},
"result": {}
}
],
"summary": {},
"keyterms": [
"<string>"
]
}
}{
"success": false,
"errors": [
"<string>"
]
}{
"success": false,
"errors": [
"<string>"
]
}Calls
Find an AI Phone Call by Custom Attribute
Find the most recent Simple AI phone call matching a custom parameter or external identifier key and value supplied by your system.
GET
/
calls
/
find_by_attribute
Find Call by Attribute
curl --request GET \
--url https://api.usesimple.ai/api/v1/calls/find_by_attribute \
--header 'Authorization: <api-key>'import requests
url = "https://api.usesimple.ai/api/v1/calls/find_by_attribute"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://api.usesimple.ai/api/v1/calls/find_by_attribute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usesimple.ai/api/v1/calls/find_by_attribute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usesimple.ai/api/v1/calls/find_by_attribute"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.usesimple.ai/api/v1/calls/find_by_attribute")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usesimple.ai/api/v1/calls/find_by_attribute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"call": {
"id": 123,
"simple_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"from_number": "<string>",
"to_number": "<string>",
"status": "<string>",
"started_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"duration": 123,
"created_at": "2023-11-07T05:31:56Z",
"prompt": {
"prompt_text": "<string>",
"created_at": "2023-11-07T05:31:56Z"
},
"transcripts": [
{
"text": "<string>",
"role": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"function_name": "<string>",
"arguments": {}
}
],
"call_prompt": "<string>",
"answered_by": "voicemail",
"record": true,
"language": "en",
"transferred": true,
"handoff_metadata": {
"five9": {
"conversation_id": "<string>",
"tenant_name": "<string>",
"campaign_name": "<string>",
"transferred_at": "2023-11-07T05:31:56Z"
}
},
"direction": "<string>",
"tags": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"description": "<string>",
"color": "<string>"
}
],
"voice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"background_noise": "<string>",
"agent_speaks_first": true,
"agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_branch": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_commit_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_branch_name": "<string>",
"external_identifiers": {},
"params": {},
"recording_presigned_url": "<string>",
"analyzers": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {
"type": "string",
"properties": {}
}
}
],
"analysis_results": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"analyzer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"prompt": "<string>",
"output_config": {},
"result": {}
}
],
"summary": {},
"keyterms": [
"<string>"
]
}
}{
"success": false,
"errors": [
"<string>"
]
}{
"success": false,
"errors": [
"<string>"
]
}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’sparams 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 theparamsfield contains the specified key-value pair
Search by External Identifiers
external_identifier_key+external_identifier_value: Search for a call where theexternal_identifiersfield contains the specified key-value pair
Example Use Cases
- Find a call by customer ID:
GET /calls/find_by_attribute?external_identifier_key=customer_id&external_identifier_value=CUST-123456 - Find a call by appointment type:
GET /calls/find_by_attribute?param_key=appointment_type¶m_value=morning - Return only fields needed by an IVR or reporting integration:
GET /calls/find_by_attribute?param_key=sip.headers.x_callsessionid¶m_value=SESSION-ID&fields=id,summary,status,params.disposition
Compact responses
Use the optionalfields 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:
{
"success": true,
"call": {
"id": "346fe020-e8c2-4abe-9d40-a4992b016bd6",
"summary": "The caller confirmed their appointment.",
"status": "completed",
"params": {
"disposition": "confirmed"
}
}
}
null. Unsupported fields return a validation error. When fields is omitted, the endpoint returns the complete call details for backward compatibility.
Response
Returns aCallFindByAttributeResponse object containing:
success: Boolean indicating if a call was foundcall: The requested compact fields, or the full call details whenfieldsis 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
Query Parameters
The key to search for in the call's params field
The value to match for the specified param_key
The key to search for in the call's external_identifiers field
The value to match for the specified external_identifier_key
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:
1000Example:
"id,summary,status,params.disposition"
Last modified on September 3, 2026