Calls

Make an outbound call

Pass the registered from_number and the destination to_number. Use variables to inject per-call context (e.g., the customer’s name or order ID) into the agent’s first message and system prompt.

curl -X POST https://api-tokyo.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "to_number": "+919876543210",
    "from_number": "+15739693824",
    "variables": { "customer_name": "Sama", "order_id": "ORD-001" },
    "webhook_url": "https://your-server.com/per-call-webhook",
    "out_sms": false
  }'

Optional field	Default	What it does
`variables`	`{}`	Key-value pairs injected into the agent’s system prompt and first message at call time
`webhook_url`	—	Per-call webhook URL — overrides any global webhook for this call only
`out_sms`	`false`	Send an SMS to `to_number` after the call ends
`schedule_at`	—	ISO 8601 timestamp to schedule the call for a future time

{
  "id": "call_abc123",
  "status": "initiated",
  "to_number": "+919876543210",
  "from_number": "+15739693824"
}

The call goes through these states:

Status	Meaning
`initiated`	Call created, connecting through your provider
`in_progress`	Call connected, agent is talking
`completed`	Call ended normally
`failed`	Call failed to connect

Receive inbound calls

When someone dials your registered number, OneInbox routes the call to your agent automatically — no extra API call needed. The call record appears in your account just like an outbound call, with the same status, outcome, transcript, and recording_url fields. To enable inbound on a number, set inbound_routing when you register or purchase it:

"inbound_routing": {
  "agent_id": "<routing_agent_id>",
  "fallback": { "agent_id": "<fallback_agent_id>" },
  "voicemail_message": "Sorry we missed you, please leave a message."
}

To add or update routing on an existing number:

curl -X PATCH https://api-tokyo.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "voicemail_message": "Updated voicemail message."
    }
  }'

→ Phone numbers — full setup for search, purchase, and bring-your-own-number paths

Stop a call

Send a stop request to end the session. If the agent already ended the call via the end_call tool, this is a no-op.

curl -X POST https://api-tokyo.oneinbox.ai/v1/calls/<call_id>/stop \
  -H "Authorization: Bearer <api_key>"

Read the results

After the call ends, fetch the full record to get the transcript, outcome, and summary. Wait 2–3 seconds after stopping — the transcript and analysis are written asynchronously.

curl https://api-tokyo.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"

{
  "id": "call_abc123",
  "status": "completed",
  "duration_seconds": 87,
  "messages": [
    { "role": "agent", "content": "Hi Sama! This is Aria from Acme." },
    { "role": "user",  "content": "Oh hi, yes I've been expecting your call." }
  ],
  "outcome": "Appointment Booked",
  "ai_summary": "Caller agreed to a product demo on Thursday at 3pm.",
  "analysis": {
    "summary": "Caller agreed to a product demo on Thursday at 3pm."
  },
  "recording_url": "https://storage.oneinbox.ai/recordings/call_abc123.mp3",
  "latency": {
    "llm_ttft": { "avg_ms": 857, "p50_ms": 820, "min_ms": 710, "max_ms": 1050, "samples": 4 },
    "tts_ttfb": { "avg_ms": 312, "p50_ms": 290, "min_ms": 240, "max_ms": 410, "samples": 4 },
    "eou_delay": { "avg_ms": 180, "p50_ms": 175, "min_ms": 140, "max_ms": 230, "samples": 4 }
  },
  "credits_used": 1.45,
  "cost_cents": 8.7
}

messages and analysis are only populated after the call ends. Stop first, wait 2–3 seconds, then fetch.

Field	When it’s available	What it means
`latency.llm_ttft`	After call ends	Time-to-first-token from the LLM — per turn, with avg/p50/min/max
`latency.tts_ttfb`	After call ends	Time-to-first-byte from TTS — per turn
`latency.eou_delay`	After call ends	End-of-utterance detection lag — how long before the agent started responding
`credits_used`	After call ends	OneInbox billing units — `duration_seconds ÷ 60` (1 credit per active minute)
`cost_cents`	Finalized async by carrier	Raw carrier cost (Twilio/Telnyx). May be `null` immediately after hangup — backfilled once the carrier finalizes
`recording_url`	After call ends (if enabled)	Pre-signed S3 URL, valid 4 hours. Each GET returns a fresh URL so it never expires for active integrations

List calls

Returns your most recent calls. Default order is newest first.

curl https://api-tokyo.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>"

List calls — cursor pagination

For large result sets, use cursor-based pagination. Pass the cursor token from the previous response to get the next page.

# First page
curl "https://api-tokyo.oneinbox.ai/v1/calls/cursor?limit=20" \
  -H "Authorization: Bearer <api_key>"

# Next page — use the cursor from the previous response
curl "https://api-tokyo.oneinbox.ai/v1/calls/cursor?cursor=<cursor>&limit=20" \
  -H "Authorization: Bearer <api_key>"

The response includes a cursor token. When cursor is null, you have reached the last page.

Delete a call

Permanently deletes a call record.

curl -X DELETE https://api-tokyo.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"

Manually set a call outcome

After a call ends you can override the AI-assigned outcome — useful when your CRM or a human reviewer has classified the call differently.

curl -X PATCH https://api-tokyo.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "interested" }'

The updated outcome value is immediately reflected in GET /v1/calls/<call_id> and in webhook payloads for that call.

What is an outcome?

An outcome is a label assigned to a completed call that summarises its result. It’s the top-level outcome field on the call record, set automatically after the call ends. analysis is a separate object holding the AI-generated summary — it does not contain outcome. You can also set or override outcome manually, and you can create your own custom outcome labels for your workspace.

Built-in outcome labels

OneInbox ships with a set of platform-level outcomes available to every account. GET /v1/workspace/call-outcomes returns their snake_case identifiers; the outcome field on a call record stores the human-readable Title Case form:

Identifier (`call-outcomes` catalog)	Stored on `call.outcome`	What it means
`appointment_booked`	`Appointment Booked`	A meeting or demo was scheduled
`callback_requested`	`Callback Requested`	Caller asked to be called back later
`completed`	`Completed`	Call finished with no other outcome matched
`do_not_call`	`Do Not Call`	Caller asked not to be contacted again
`failed`	`Failed`	Call failed to connect properly
`interested`	`Interested`	Caller engaged but did not commit
`no_answer`	`No Answer`	Call rang out with no pickup
`not_connected`	`Not Connected`	No conversation happened (busy, immediate hang-up)
`not_interested`	`Not Interested`	Caller explicitly declined
`other`	`Other`	Doesn’t match any other label
`spam`	`Spam`	Identified as a spam/robocall situation
`voicemail`	`Voicemail`	Voicemail greeting detected
`wrong_number`	`Wrong Number`	Reached the wrong person/number
—	`null`	No outcome classified — call too short or ambiguous

How auto-classification works

After every call ends, OneInbox reads the transcript and assigns an outcome automatically. No configuration needed. A few things to know:

Classification happens post-call. outcome is null during an active call. Fetch the record after the call ends.
ai_summary explains the reasoning. If an outcome looks wrong, read the summary to understand what the model saw in the conversation.
Custom outcomes are also used. If you have created custom outcome labels (see below), the agent uses those in addition to the built-in set when classifying calls.

Custom outcome labels

You can create custom outcome labels specific to your workspace. The agent uses these alongside the built-in labels when classifying calls — so if you add “Hot Lead” as a custom outcome, the AI will start assigning it when a call matches that description.

List call outcomes

Returns both the built-in platform labels (always available) and any custom labels you have created for your workspace.

curl https://api-tokyo.oneinbox.ai/v1/workspace/call-outcomes \
  -H "Authorization: Bearer <api_key>"

{
  "builtin": [
    "appointment_booked", "callback_requested", "completed", "do_not_call",
    "failed", "interested", "no_answer", "not_connected", "not_interested",
    "other", "spam", "voicemail", "wrong_number"
  ],
  "items": [
    {
      "id": "co_abc123",
      "label": "Hot Lead",
      "description": "Expressed strong interest and asked specific product questions",
      "is_active": true
    }
  ],
  "total": 1
}

Create a custom outcome

Add a new outcome label to your workspace. Any casing is accepted — e.g. "Hot Lead" or "demo_scheduled". Once created, the agent starts using it automatically when classifying future calls.

curl -X POST https://api-tokyo.oneinbox.ai/v1/workspace/call-outcomes \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Hot Lead",
    "description": "Qualified lead with confirmed budget and decision timeline"
  }'

{
  "id": "co_abc123",
  "label": "Hot Lead",
  "description": "Qualified lead with confirmed budget and decision timeline",
  "is_active": true
}

Field	What it does
`label`	The outcome name. Any casing is accepted — stored and displayed as-is
`description`	Optional. Explains to the AI when this outcome applies. More detail = more accurate classification

Update a custom outcome

Rename a label or deactivate it. Deactivating (is_active: false) hides the outcome from future auto-classification but preserves it on historical call records — no data is lost.

curl -X PATCH https://api-tokyo.oneinbox.ai/v1/workspace/call-outcomes/<outcome_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Qualified Lead",
    "is_active": true
  }'

Field	What it does
`label`	New label name — updates how it appears on call records going forward
`is_active`	`false` = hides this outcome from new classification while keeping historical data intact

Get notified automatically with webhooks

Instead of polling, set up a webhook to receive the full call record as soon as a call ends:

curl -X POST https://api-tokyo.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Call completed",
    "url": "https://your-server.com/webhooks/oneinbox",
    "events": ["call.ended"]
  }'

→ Webhooks guide

API reference

Create outbound call · Stop call · Get call · Update call · List calls · Delete call · List call outcomes · Create call outcome · Update call outcome

Get started

Make calls

Configure your agent

Monitor & integrate

Core concepts

Make an outbound call

Receive inbound calls

Stop a call

Read the results

List calls

Delete a call

Manually set a call outcome

What is an outcome?

Built-in outcome labels

How auto-classification works

Custom outcome labels

List call outcomes

Create a custom outcome

Update a custom outcome

Get notified automatically with webhooks

API reference

​Make an outbound call

​Receive inbound calls

​Stop a call

​Read the results

​List calls

​List calls — cursor pagination

​Delete a call

​Manually set a call outcome

​What is an outcome?

​Built-in outcome labels

​How auto-classification works

​Custom outcome labels

​List call outcomes

​Create a custom outcome

​Update a custom outcome

​Get notified automatically with webhooks

​API reference

Make an outbound call

Receive inbound calls

Stop a call

Read the results

List calls

List calls — cursor pagination

Delete a call

Manually set a call outcome

What is an outcome?

Built-in outcome labels

How auto-classification works

Custom outcome labels

List call outcomes

Create a custom outcome

Update a custom outcome

Get notified automatically with webhooks

API reference