# Voice, recordings and transfers

## Outbound and inbound

`POST /v1/calls {to,line?,objective?,purpose?,planned_seconds?,max_duration_seconds?}`
requires `voice.outbound` and the Line binding, policy and budgets.
`max_duration_seconds` is 30–3600 (default 1800), cut to whole affordable
billing increments. Unverified routes are refused before execution.

Lifecycle: `authorized → routing → ringing → connected → completed`, with
`failed`, `busy`, `no_answer`, `canceled` terminal alternatives. Carrier
timestamps drive accounting: `answered_at` is carrier evidence, not HTTP
request time. Missing answer or cost evidence stays `pending` and is
reconciled from carrier records — never assumed free.

An inbound call routes to the Line's authorized agent. Poll
`/calls?status=ringing` or receive `call.received`; the agent answers with
`/calls/{id}/answer` (`voice.inbound`). The platform snapshots the call's
verified price at arrival — answering requires that snapshot. Decline or
end with `/hangup` when delegated. Carrier limits and platform backstops
enforce budgets and withdrawn authority; any real overrun is still
recorded honestly.

`objective` does not synthesize speech. ORDan does not supply agent
intelligence — external runtimes do. Connect your runtime to the call to
converse.

## DTMF and records

`POST /calls/{id}/dtmf {digits,duration_ms?,sensitive?}` requires
`calls.dtmf`. Digits: `0-9 * # A-D w W`, 1–64 characters; `w/W` pause. Set
`sensitive: true` for PIN/account sequences so the ledger masks them.

`/recording/start` and `/recording/stop` require `calls.record`.
Recording is an explicit, separately-priced feature with minimum and
increment rounding; recorded seconds round upward. Audio stays at the
carrier: authorized owners/keys get a short-lived retrieval link; agents
receive recording summaries, not owner audio.

Report `/transcript {segments:[{role:"agent"|"human",text,at_seconds?}],text?}`
and `/outcome {outcome,summary?,...}` once after answering. These are your
runtime's reports — ORDan supplies measured duration and preserves
append-only records.

## Transfers

`POST /calls/{id}/transfer {to,purpose?,category?,approval?}` requires
`calls.transfer` (or an authorized owner/key). It reserves an invocation
fee plus a **separately quoted outbound target leg** using the owned
Line's caller ID. The returned `transfer: xfer_…` identifies the action.

Leg B has independent correlation, time limit and cost hold; its events
cannot re-price Leg A. A failed or unanswered leg still incurs the
invocation fee where carrier evidence confirms it. Terminal events are
`call.transfer.completed` / `call.transfer.failed`, with
`call.transfer.billing.settled` for delayed financial settlement.