# AgentPhone — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orthogonal.com/v1/run` · [llms.txt](https://orthogonal.com/llms.txt) · [browse all APIs](https://orthogonal.com/discover)

Give your AI agent a real phone number. Make calls, send and receive messages across iMessage, WhatsApp, SMS and more to have conversations in the real world — all via API.

**Verified:** yes

## Access

**Run API:** `POST https://api.orthogonal.com/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://orthogonal.com/dashboard/settings/api-keys

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "price": "<usd>", "data": { ... } }`.

## Endpoints

### Verify Signup

Verify OTP code. Atomically creates account, provisions phone number, creates starter agent, returns API key. No auth required.

`POST /v0/agent/verify`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `verification_id` | string | Yes | verification_id from sign-up. |
| `otp_code` | string | Yes | 6-digit code from email. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v0/agent/verify","body":{"verification_id":"<string>","otp_code":"<string>"}}'
```

### Update Agent

Update agent fields. Only sent fields change.

`PATCH /v1/agents/{agentId}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `name` | string | No | Display name. |
| `voiceMode` | string | No | hosted or webhook. |
| `systemPrompt` | string | No | Agent instructions. |
| `beginMessage` | string | No | First line. |
| `voice` | string | No | Voice ID. |
| `modelTier` | string | No | turbo, balanced, or max. |
| `transferNumber` | string | No | E.164 transfer number. |
| `voicemailMessage` | string | No | Voicemail message. |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}","method":"PATCH","body":{"name":"<string>","voiceMode":"<string>","systemPrompt":"<string>","beginMessage":"<string>","voice":"<string>","modelTier":"<string>","transferNumber":"<string>","voicemailMessage":"<string>"}}'
```

### Detach Number from Agent

Detach a phone number from an agent.

`DELETE /v1/agents/{agentId}/numbers/{numberId}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `numberId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {agentId}, {numberId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}/numbers/{numberId}","method":"DELETE"}'
```

### List Voices

List all available voices across providers (ElevenLabs, Cartesia, OpenAI, etc).

`GET /v1/agents/voices`

**Cost:** Free

_No parameters required._

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/voices","method":"GET"}'
```

### Set Agent Webhook

Set webhook URL for a specific agent.

`POST /v1/agents/{agentId}/webhook`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `url` | string | Yes | Webhook URL. |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}/webhook","body":{"url":"<string>"}}'
```

### Get Agent Webhook

Get webhook URL for a specific agent.

`GET /v1/agents/{agentId}/webhook`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}/webhook","method":"GET"}'
```

### Delete Agent

Permanently delete an agent. Cannot be undone.

`DELETE /v1/agents/{agentId}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}","method":"DELETE"}'
```

### Sign Up

Start agent signup. Sends a 6-digit OTP to the human's email. Returns a verification_id. No auth required.

`POST /v0/agent/sign-up`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `human_email` | string | Yes | Human's email address. OTP is sent here. |
| `agent_name` | string | No | Name for the starter agent. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v0/agent/sign-up","body":{"human_email":"<string>","agent_name":"<string>"}}'
```

### Get Call

Get call details and transcript. Poll until status is completed or failed.

`GET /v1/calls/{callId}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `callId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {callId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/calls/{callId}","method":"GET"}'
```

### Get Conversation

Get a conversation with all messages.

`GET /v1/conversations/{conversationId}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `conversationId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {conversationId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/conversations/{conversationId}","method":"GET"}'
```

### List Agent Conversations

List SMS conversations for a specific agent.

`GET /v1/agents/{agentId}/conversations`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}/conversations","method":"GET"}'
```

### Create Agent

Create a new agent with name, voice, system prompt, and voice mode.

`POST /v1/agents`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name. |
| `voiceMode` | string | No | hosted or webhook. |
| `systemPrompt` | string | No | Agent instructions for hosted calls. |
| `beginMessage` | string | No | First line on call connect. |
| `voice` | string | No | Voice ID from GET /v1/agents/voices. |
| `modelTier` | string | No | turbo, balanced, or max. |
| `transferNumber` | string | No | E.164 number to transfer calls to. |
| `voicemailMessage` | string | No | Voicemail message. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents","body":{"name":"<string>","voiceMode":"<string>","systemPrompt":"<string>","beginMessage":"<string>","voice":"<string>","modelTier":"<string>","transferNumber":"<string>","voicemailMessage":"<string>"}}'
```

### Get Agent

Get details for a specific agent.

`GET /v1/agents/{agentId}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}","method":"GET"}'
```

### Buy Number

Buy a US or CA phone number. $3/month per number.

`POST /v1/numbers`

**Estimated cost:** $3.5

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | Yes | US or CA. |
| `areaCode` | string | No | 3-digit area code. |
| `agentId` | string | No | Agent ID to attach immediately. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/numbers","body":{"country":"<string>","areaCode":"<string>","agentId":"<string>"}}'
```

### Attach Number to Agent

Attach a phone number to an agent.

`POST /v1/agents/{agentId}/numbers`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `numberId` | string | Yes | Number ID (num_xxx). |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}/numbers","body":{"numberId":"<string>"}}'
```

### Release Number

Release a phone number. Irreversible.

`DELETE /v1/numbers/{numberId}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `numberId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {numberId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/numbers/{numberId}","method":"DELETE"}'
```

### List Agent Calls

List calls for a specific agent.

`GET /v1/agents/{agentId}/calls`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {agentId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/agents/{agentId}/calls","method":"GET"}'
```

### List Messages

List messages for a phone number.

`GET /v1/numbers/{numberId}/messages`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `numberId` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `limit` | number | No | Max messages to return. |

```bash
# Replace {numberId} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/numbers/{numberId}/messages","method":"GET","query":{"limit":"<number>"}}'
```

### Send SMS

Send an SMS from an agent's phone number. First message compliance: Your initial SMS to any new contact must include (1) your brand name, (2) opt-in confirmation, and (3) opt-out instructions (e.g., "Reply STOP to unsubscribe"). Non-compliant first messages may be silently filtered by carriers.

`POST /v1/messages`

**Estimated cost:** $0.03

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agent_id` | string | Yes | Agent sending the message. |
| `to_number` | string | Yes | Recipient in E.164 format. |
| `body` | string | Yes | Message text. |
| `media_url` | string | No | URL for MMS attachment. |
| `number_id` | string | No | Specific number to send from. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/messages","body":{"agent_id":"<string>","to_number":"<string>","body":"<string>","media_url":"<string>","number_id":"<string>"}}'
```

### Make Call

Make an outbound voice call. Include systemPrompt for autonomous AI conversation, omit for webhook-driven mode.

`POST /v1/calls`

**Estimated cost:** $0.1

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentId` | string | Yes | Agent placing the call. |
| `toNumber` | string | Yes | Recipient in E.164 format. |
| `systemPrompt` | string | No | Instructions for autonomous mode. |
| `initialGreeting` | string | No | First line the AI says. |
| `fromNumberId` | string | No | Specific number to call from. |
| `voice` | string | No | Override agent default voice. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentphone","path":"/v1/calls","body":{"agentId":"<string>","toNumber":"<string>","systemPrompt":"<string>","initialGreeting":"<string>","fromNumberId":"<string>","voice":"<string>"}}'
```

---

Full details and an interactive quickstart: https://orthogonal.com/discover/agentphone