Quickstart

Overview

In a few minutes you will have a working voice agent with its own phone number, and you’ll have made a real outbound call with it. You will:

Create an agent
Purchase a phone number — directly through OneInbox, no Twilio account needed
Make a call
Check the results

Every API request uses:

Authorization: Bearer <api_key>

Prerequisites

Item	Where
OneInbox API key	Dashboard → API Keys → Create API key
Terminal	`curl` (Mac Terminal, Windows PowerShell, or WSL)

Step 1 — Create an agent

One API call. Give it a name — OneInbox automatically configures a default LLM, voice, and system prompt. The agent is ready to take calls immediately.

curl -X POST https://api-tokyo.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My First Agent" }'

{
  "id": "agt_abc123",
  "name": "My First Agent",
  "llm_id": "llm_xyz789",
  "created_at": "2026-06-01T10:00:00Z"
}

Save both IDs from the response:

id — the agent (voice, language, call behavior)
llm_id — the AI brain (what it knows and can do). They’re separate so multiple agents can share one brain.

Step 2 — Purchase a phone number

Buy a number directly through OneInbox — no Twilio or telephony account needed. Option A — Search and pick a specific number:

# 1. Search available numbers
curl "https://api-tokyo.oneinbox.ai/v1/phone-numbers/search?country=US&area_code=415&limit=10" \
  -H "Authorization: Bearer <api_key>"

# 2. Purchase the one you want
curl -X POST https://api-tokyo.oneinbox.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "My First Number",
    "agent_id": "<agent_id>"
  }'

Option B — Auto-assign (skip the search):

curl -X POST https://api-tokyo.oneinbox.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "area_code": "415",
    "friendly_name": "My First Number",
    "agent_id": "<agent_id>"
  }'

{
  "id": "phn_abc123",
  "phone_number": "+14155551234",
  "agent_id": "agt_abc123",
  "status": "active"
}

Your number is now live both ways: it can call out, and anyone who dials it reaches your agent automatically.

Already have a number in Twilio you’d rather use? See Phone numbers for the bring-your-own-number path.

Step 3 — Make a call

Call any number you want, using your new number as the caller ID:

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": "+14155551234"
  }'

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

Your phone rings — answer it to talk to your agent live.

Step 4 — Check call results

After the call ends, fetch the record:

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

{
  "id": "call_abc123",
  "status": "completed",
  "duration_seconds": 45,
  "messages": [
    { "role": "agent", "content": "Hi! How can I help?" },
    { "role": "user", "content": "I have a question about my order" }
  ],
  "outcome": "Interested",
  "ai_summary": "Caller asked about order status. Agent provided tracking info."
}

messages, outcome, and ai_summary are only available after the call ends.

Customize your agent

Your agent works out of the box with defaults. When you’re ready to tailor it to your use case, update it without rebuilding anything.

Give it a personality

Set a system prompt to define the agent’s role and behaviour, and a first message to control how it opens every call:

# Set a system prompt on the LLM
curl -X PATCH https://api-tokyo.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a helpful support agent for Acme Corp. Keep replies under two sentences. When the caller says goodbye, call end_call.",
    "temperature": 0.7
  }'

# Set a first message and call behaviour on the agent
curl -X PATCH https://api-tokyo.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_message": "Hi! Thanks for reaching out to Acme. How can I help?",
    "silence_timeout_seconds": 10,
    "enable_recording": true
  }'

Add tools

Tools let your agent take actions during a call — transfer to a human, end the call, send an SMS, book a meeting, and more. Create each tool, then attach them to the LLM:

# Transfer to a human agent
curl -X POST https://api-tokyo.oneinbox.ai/v1/tools \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "transfer_to_human",
    "type": "transfer_call",
    "description": "Transfer to a human when the caller asks to speak to a person.",
    "transfer_to": "+15105550100"
  }'

# End the call cleanly
curl -X POST https://api-tokyo.oneinbox.ai/v1/tools \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "end_call",
    "type": "end_call",
    "description": "End the call after the task is done or the caller says goodbye."
  }'

# Attach both tools to the LLM
curl -X PATCH https://api-tokyo.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids": ["<transfer_tool_id>", "<end_call_tool_id>"]
  }'

See Tools for the full list — SMS, email, calendar booking, data extraction, and more.

Add a knowledge base

Give your agent a document or URL to answer questions from:

# Create a knowledge base source
curl -X POST https://api-tokyo.oneinbox.ai/v1/knowledge-bases \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product FAQ",
    "source_type": "url",
    "url": "https://acme.com/faq"
  }'

# Attach the knowledge base to the agent
curl -X PATCH https://api-tokyo.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_ids": ["<kb_id>"]
  }'

See Knowledge bases for uploading files, syncing URLs, and managing sources.

Next steps

Agents

Voice, language, recording, and behaviour settings

Tools

Give your agent actions — SMS, email, data capture, transfer

Knowledge bases

Upload docs or sync URLs for your agent to answer from

Phone numbers

Bring your own Twilio number, or learn more about outbound/inbound

Get started

Make calls

Configure your agent

Monitor & integrate

Core concepts

Overview

Prerequisites

Step 1 — Create an agent

Step 2 — Purchase a phone number

Step 3 — Make a call

Step 4 — Check call results

Customize your agent

Give it a personality

Add tools

Add a knowledge base

Next steps

Agents

Tools

Knowledge bases

Phone numbers

​Overview

​Prerequisites

​Step 1 — Create an agent

​Step 2 — Purchase a phone number

​Step 3 — Make a call

​Step 4 — Check call results

​Customize your agent

​Give it a personality

​Add tools

​Add a knowledge base

​Next steps

Agents

Tools

Knowledge bases

Phone numbers

Overview

Prerequisites

Step 1 — Create an agent

Step 2 — Purchase a phone number

Step 3 — Make a call

Step 4 — Check call results

Customize your agent

Give it a personality

Add tools

Add a knowledge base

Next steps