Skip to main content
PATCH
Tag or archive a call

Authorizations

Authorization
string
header
required

An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.

Headers

If-Match
string
required

The revision you read (its ETag, an integer in quotes such as "7"), so a stale write is refused with 412. Required: a write without it is refused with 428.

Pattern: ^(W/)?"?[0-9]+"?$
Example:

"\"7\""

Kallabot-Version
enum<string>

The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.

Available options:
2026-11-07
Example:

"2026-11-07"

Path Parameters

call_id
string
required

Body

application/json

Tags, the review flag and archiving. Send only what changes.

tags
string[] | null
Maximum array length: 40
Maximum string length: 80
attention
enum<string> | null
Available options:
none,
needs_review,
reviewed
archived
boolean | null

Response

Successful Response

id
string
required

The call's id (call_…).

channel
enum<string>
required

phone, or web for a browser call.

Available options:
phone,
web
direction
enum<string>
required

Whether the agent answered it or made it.

Available options:
inbound,
outbound
lifecycle
enum<string>
required

Where the call is now. completed, failed and canceled are final.

Available options:
requested,
queued,
dialing,
ringing,
connected,
ending,
completed,
failed,
canceled
outcome
enum<string> | null
required

How it ended; null while it is live.

Available options:
answered,
busy,
no_answer,
rejected,
abandoned,
provider_failed,
runtime_failed,
canceled,
unknown
desired_state
enum<string>
required

A stop you asked for that the carrier hasn't confirmed yet.

Available options:
none,
cancel_requested,
hangup_requested
attention_state
enum<string>
required

The review flag: needs_review until someone marks it reviewed.

Available options:
none,
needs_review,
reviewed
revision
integer
required

Bumped on every change. Send it back as If-Match on a write.

agent_id
string | null
required

The agent on the call.

agent_version
integer | null
required

The agent version the call ran.

party
string | null
required

The external party, masked.

party_country
string | null
required

The external party's country (ISO 3166-1 alpha-2).

actor_user_id
string | null
required

The person who placed it, if one did.

team_id
string | null
required

The team it belongs to, if any.

requested_at
string
required

When it was requested (ISO 8601).

answered_at
string | null
required

When it was answered (ISO 8601).

ended_at
string | null
required

When it ended (ISO 8601).

ring_ms
integer | null
required

How long it rang.

talk_ms
integer | null
required

How long the conversation lasted.

total_ms
integer | null
required

Ringing plus talking.

attempt_count
integer
required

Dial attempts made.

terminal_reason
string | null
required

Why it ended, in a stable code.

error_code
string | null
required

An error code when it failed.

usage_finalization
string
required

Whether the minutes used are final yet.

cost_finalization
string
required

Whether the cost is final yet (complete once settled).

telemetry_completeness
string
required

Whether every call event arrived.

has_recording
boolean
required

A recording can be downloaded.

has_transcript
boolean
required

A transcript can be read.

transferred
boolean
required

The caller was moved to a person or number.

transfer_destination
string | null
required

Where it was transferred to, masked.

transfer_type
string | null
required

How it was transferred.

transfer_at
string | null
required

When it was transferred (ISO 8601).

capabilities
CallCapabilities · object
required

What this key may do to this call.

analysis_state
enum<string>
default:pending

Whether the post-call analysis has run.

Available options:
pending,
running,
complete,
skipped,
failed
analyzed_at
string | null

When the analysis ran (ISO 8601).

disposition
string | null

What the call achieved, e.g. booked or callback.

sentiment
number | null

The caller's mood, from -1 (negative) to 1 (positive).

sentiment_label
string | null

positive, neutral or negative.

summary
string | null

A short summary. Null without call:content.

caller_name
string | null

The caller's name, if they gave it. Null without call:content.

caller_company
string | null

The caller's company. Null without call:content.

caller_email
string | null

The caller's email. Null without call:content.

callback_at
string | null

When the caller asked to be called back (ISO 8601).

tags
string[]

Labels on the call.

review_reasons
string[]

Why it was flagged for review.

reviewed_at
string | null

When it was marked reviewed (ISO 8601).

archived_at
string | null

When it was archived (ISO 8601).

cost_total_micros
integer | null

The call's cost in millionths of currency, once settled.

currency
string | null

The cost's currency (ISO 4217), once settled.