Find Call by Attribute

curl --request GET \
  --url https://api.prod.usesimple.ai/api/v1/calls/find_by_attribute \
  --header 'Authorization: <api-key>'

{
  "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,
    "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,
    "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": {}
  }
}

GET

calls

find_by_attribute

Find Call by Attribute

curl --request GET \
  --url https://api.prod.usesimple.ai/api/v1/calls/find_by_attribute \
  --header 'Authorization: <api-key>'

{
  "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,
    "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,
    "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": {}
  }
}

Overview

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

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&param_value=morning

Response

Returns a CallFindByAttributeResponse object containing:

success: Boolean indicating if a call was found
call: The full call details (same as the Get Call endpoint) if found

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

Response

Successful Response

success

boolean

required

Indicates if the request was successful

call

CallDetailsResponse · object

required

The call details if found

Show child attributes

call.id

integer

required

call.simple_uuid

string<uuid>

required

call.from_number

string

required

call.to_number

string

required

call.status

string

required

call.started_at

string<date-time> | null

required

call.ended_at

string<date-time> | null

required

call.duration

integer | null

required

call.created_at

string<date-time>

required

call.prompt

CallPromptResponse · object

required

Show child attributes

call.prompt.prompt_text

string

required

call.prompt.created_at

string<date-time>

required

call.transcripts

CallTranscriptResponse · object[]

required

Show child attributes

call.transcripts.text

string | null

required

call.transcripts.role

string

required

call.transcripts.timestamp

string<date-time>

required

call.transcripts.function_name

string | null

required

call.transcripts.arguments

Arguments · object

required

call.call_prompt

string

required

call.answered_by

enum<string>

required

Indicates how the call was answered - by a human, voicemail, or if there was no answer

Available options:

voicemail,

human,

no_answer,

unknown

call.record

boolean

call.language

enum<string>

The language to use for the call - English (en) or Spanish (es)

Available options:

en,

es,

ar

call.transferred

boolean

Indicates if the call was transferred

call.direction

string

The direction of the call (inbound/outbound)

call.tags

Tags · object[]

Tags associated with the call

Show child attributes

call.tags.id

string<uuid>

call.tags.name

string

call.tags.description

string

call.tags.color

string

call.voice_id

string<uuid> | null

The ID of the voice used for the call

call.background_noise

string | null

The background noise setting for the call

call.agent_speaks_first

boolean | null

Whether the agent speaks first in the call

call.external_identifiers

External Identifiers · object

External identifiers associated with the call

Show child attributes

call.external_identifiers.{key}

string

call.params

Params · object

Parameters associated with the call

Show child attributes

call.params.{key}

string

call.recording_presigned_url

string | null

call.analyzers

AnalyzerResponse · object[]

List of analyzers configured for this call

Show child attributes

call.analyzers.id

string<uuid>

required

Unique identifier for the analyzer

call.analyzers.prompt

string

required

The prompt used for analysis

call.analyzers.output_config

Output Config · object

required

Configuration for the expected output format

Show child attributes

call.analyzers.output_config.type

enum<string>

The type of output expected

Available options:

string,

boolean,

datetime,

object

call.analyzers.output_config.properties

object

Required when type is 'object'. Defines the structure of the object

Show child attributes

call.analyzers.output_config.properties.{key}

object

Show child attributes

call.analyzers.output_config.properties.{key}.type

enum<string>

Available options:

string,

boolean,

datetime

call.analysis_results

AnalysisResultResponse · object[]

Results from analyzers that have completed

Show child attributes

call.analysis_results.id

string<uuid>

required

Unique identifier for the analysis result

call.analysis_results.analyzer_id

string<uuid>

required

Identifier of the analyzer that produced this result

call.analysis_results.prompt

string

required

The prompt used for analysis

call.analysis_results.output_config

Output Config · object

required

Configuration for the expected output format

call.analysis_results.result

Result · object

required

The analysis result, structure depends on the output_config

call.summary

Summary · object

The summary of the call if available

List Calls Delete Call

⌘I

API Documentation

Simple Example

Calls

Call Tags

Call Notes

Agents

Numbers

Voices

Webhooks

Find Call by Attribute

Overview

Search Options

Search by Parameters

Search by External Identifiers

Example Use Cases

Response

Notes

Authorizations

Query Parameters

Response

API Documentation

Simple Example

Calls

Call Tags

Call Notes

Agents

Numbers

Voices

Webhooks

​Overview

​Search Options

​Search by Parameters

​Search by External Identifiers

​Example Use Cases

​Response

​Notes

Authorizations

Query Parameters

Response

Overview

Search Options

Search by Parameters

Search by External Identifiers

Example Use Cases

Response

Notes