Calls

Create and manage outbound voice calls. The public API creates outbound calls only. Inbound calls are handled automatically when a phone number is assigned to an agent. For UUID / phone / datetime formats used below, see Data formats.

List Calls

Parameters

Query parameters:

Parameter	Type	Description
`status`	string	Filter by call status (see Call Statuses)
`direction`	string	`inbound` or `outbound`
`agent_id`	UUID	Filter by agent
`limit`	integer	1–100. Default `50`
`offset`	integer	Pagination offset. Default `0`

curl "https://api.truedy.ai/api/public/v1/calls?status=completed&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

data (array of call objects), pagination (total, limit, offset, has_more), meta.

Get Call

curl "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Call

Place an outbound call using a specified agent. The call is always outbound when created via the public API.

Request Body

Field	Type	Required	Description
`agent_id`	UUID	Yes	Agent that will handle the call
`phone_number`	string (E.164)	Yes	Destination number to call (e.g. `+15551234567`)
`from_number`	string (E.164)	No	Caller ID override. Must be a number assigned to this agent for outbound. If omitted, the system selects automatically.
`variables`	object	No	Key-value pairs passed to the agent as template variables. Use in your system prompt with mustache syntax: `{{first_name}}`, `{{company}}`, etc. All values are treated as strings.
`call_settings`	object	No	Per-call overrides (see `call_settings` fields below)

`call_settings` Fields

Field	Type	Default	Description
`recording_enabled`	boolean	`true`	Record the call
`transcription_enabled`	boolean	`true`	Transcribe the call
`greeting`	string	—	Override the agent’s configured greeting for this specific call
`max_duration`	string	—	Maximum call length, e.g. `"3600s"`. Overrides agent default for this call.
`join_timeout`	string	—	Time to wait for the callee to answer, e.g. `"30s"`. Overrides agent default.

Outbound call requirements:

The agent must have at least one phone number assigned for outbound (see Telephony — Assign Number), or you must provide from_number.
If no outbound number is available, the API returns 422.
The telephony provider (Telnyx, Twilio, Plivo) is determined from the number’s credential.

Example

{
  "agent_id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
  "phone_number": "+14155550123",
  "variables": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "Acme Inc",
    "appointment_time": "2pm Thursday"
  },
  "call_settings": {
    "recording_enabled": true,
    "max_duration": "600s"
  }
}

curl -X POST "https://api.truedy.ai/api/public/v1/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 8b7e6494-3839-49dc-9638-a1944fdd8cda" \
  -d '{
    "agent_id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
    "phone_number": "+14155550123",
    "variables": { "first_name": "Jane", "company": "Acme Inc" }
  }'

Response: 201 Created with data (call object: id, agent_id, phone_number, direction, status, etc.) and meta. Send X-Idempotency-Key for safe retries.

Create Web Call

Start a browser-based voice call without a phone number. The API returns a short-lived joinUrl; pass it to the Ultravox client in your browser. This is the Web Call variant of the Calls API, not a separate product area.

curl -X POST "https://api.truedy.ai/api/public/v1/webrtc/call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"1f4baf16-1540-4d91-9696-7f34b2f2cb77"}'

The response contains data.id for the Truedy call record and data.joinUrl for the browser client. The URL is single-use and expires if it is not joined promptly. See Quickstart: Web Call for the browser integration.

Update Call

Update metadata on a call. Only context and call_settings can be updated after creation. Body: context (object, any key-value data to store on the call record) and/or call_settings (object with recording_enabled, transcription_enabled). Only included fields are updated.

curl -X PATCH "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": { "priority": "high" },
    "call_settings": { "recording_enabled": true }
  }'

Delete Call

Cannot delete active calls (queued, ringing, in_progress). Completed, failed, and other terminal calls can be deleted.

curl -X DELETE "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk Delete Calls

Body: ids — array of call UUIDs to delete. Active calls in the list are skipped. Response: data: { deleted_count, failed_count, deleted_ids, failed_ids }, meta.

curl -X POST "https://api.truedy.ai/api/public/v1/calls/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "44ec8f61-6d9a-4553-a6ca-777f5f5ef95b",
      "f89052b2-3467-4a34-b4e3-e5d1571cbb36"
    ]
  }'

Get Recording

Returns a URL to the call recording audio. The URL is fetched from the telephony provider and cached on the call record.

curl "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b/recording" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: data: { recording_url }. Returns 404 if no recording exists (e.g. recording was disabled).

Get Transcript

Returns the full transcript and summary for a completed call.

curl "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b/transcript" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: data: { transcript: [...], summary }. Returns 404 if no transcript is available yet.

Call Object

Field	Type	Description
`id`	UUID	Call ID
`agent_id`	UUID	Agent that handled the call
`phone_number`	string	The number that was called
`from_number`	string	Caller ID used
`direction`	string	`inbound` or `outbound`
`status`	string	See Call Statuses
`started_at`	datetime	When the call connected
`ended_at`	datetime	When the call ended
`duration_seconds`	integer	Total call length
`cost_usd`	float	Billed cost
`summary`	string	AI-generated call summary
`recording_url`	string	Recording URL (if enabled and available)
`context`	object	Any metadata stored on the call
`created_at`	datetime	When the call was created
`updated_at`	datetime	Last updated

Call Statuses

Status	Description
`queued`	Call created, waiting to be placed
`ringing`	Call is ringing the destination
`in_progress`	Call is active and connected
`completed`	Call ended normally
`failed`	Call could not be placed (check `context.last_error`)
`no_answer`	Callee did not answer
`busy`	Callee line was busy
`voicemail`	Call went to voicemail

Errors

HTTP Status	Code	Meaning
`422`	`validation_error`	Invalid request — missing `agent_id`, invalid phone number, or no outbound number assigned to the agent
`402`	`payment_required`	Insufficient credits or inactive subscription
`502`	`provider_error`	Telephony or voice provider error

Failed calls: When a call is created but the provider fails to place it, the call record has status: "failed". The provider error message is stored in context.last_error. Fix the underlying issue and retry.

API documentation

Endpoints

Calls

Calls

List Calls

Parameters

Response

Get Call

Create Call

Request Body

`call_settings` Fields

Example

Create Web Call

Update Call

Delete Call

Bulk Delete Calls

Get Recording

Get Transcript

Call Object

Call Statuses

Errors

​Calls

​List Calls

​Parameters

​Response

​Get Call

​Create Call

​Request Body

​call_settings Fields

​Example

​Create Web Call

​Update Call

​Delete Call

​Bulk Delete Calls

​Get Recording

​Get Transcript

​Call Object

​Call Statuses

​Errors

Calls

List Calls

Parameters

Response

Get Call

Create Call

Request Body

`call_settings` Fields

Example

Create Web Call

Update Call

Delete Call

Bulk Delete Calls

Get Recording

Get Transcript

Call Object

Call Statuses

Errors