> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build your first voice agent, get a phone number, and make a real call — no third-party telephony account required.

## 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:**

1. Create an **agent**
2. Purchase a **phone number** — directly through OneInbox, no Twilio account needed
3. **Make a call**
4. **Check the results**

Every API request uses:

```
Authorization: Bearer <api_key>
```

***

## Prerequisites

| Item                 | Where                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------- |
| **OneInbox API key** | [Dashboard](https://oneinbox-dashboard.vercel.app) → **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.

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

```json theme={null}
{
  "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:**

```bash theme={null}
# 1. Search available numbers
curl "https://api.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.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):**

```bash theme={null}
curl -X POST https://api.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>"
  }'
```

```json theme={null}
{
  "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.

<Note>
  Already have a number in Twilio you'd rather use? See [Phone numbers](/guides/phone-calls) for the bring-your-own-number path.
</Note>

***

## Step 3 — Make a call

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

```bash theme={null}
curl -X POST https://api.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"
  }'
```

```json theme={null}
{
  "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:

```bash theme={null}
curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"
```

```json theme={null}
{
  "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:

```bash theme={null}
# Set a system prompt on the LLM
curl -X PATCH https://api.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.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:

```bash theme={null}
# Transfer to a human agent
curl -X POST https://api.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.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.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](/guides/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:

```bash theme={null}
# Create a knowledge base source
curl -X POST https://api.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.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_ids": ["<kb_id>"]
  }'
```

See [Knowledge bases](/guides/knowledge-bases) for uploading files, syncing URLs, and managing sources.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/concepts/agents">
    Voice, language, recording, and behaviour settings
  </Card>

  <Card title="Tools" icon="wrench" href="/guides/tools">
    Give your agent actions — SMS, email, data capture, transfer
  </Card>

  <Card title="Knowledge bases" icon="book" href="/guides/knowledge-bases">
    Upload docs or sync URLs for your agent to answer from
  </Card>

  <Card title="Phone numbers" icon="phone" href="/guides/phone-calls">
    Bring your own Twilio number, or learn more about outbound/inbound
  </Card>
</CardGroup>