# Quickstart

Patch AMD tells you who answered an outbound call: a **person**, a **voicemail**, an **IVR** (phone menu, hold queue, call screening), an **unavailable** line (not in service, mailbox full), or **silence**. You stream the callee's audio from the moment the call is answered; we send back one decision and close the stream.

## 1. Get an API key

[Create an account](/signup), open **API keys** in the dashboard and create a key. It looks like `pamd_live_…` and is shown once. Keep it on your server.

## 2. Start a stream when the call is answered

Pick your carrier:

- **Twilio** — add `<Start><Stream>` to the TwiML your answer webhook returns. [Twilio guide](/docs/twilio)
- **Telnyx** — call `streaming_start` on `call.answered`, or pass `stream_url` when you dial. [Telnyx guide](/docs/telnyx)
- **Anything else** — open a WebSocket and send raw mu-law, A-law or 16-bit PCM frames. [Raw WebSocket guide](/docs/raw-websocket)

Carriers can't send our API key as a header, so for them you first mint a **signed stream URL** on your server:

```bash
curl -X POST https://api.patchamd.com/v1/streams \
  -H "Authorization: Bearer $PATCH_AMD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://you.example/amd", "metadata": {"lead": "42"}}'
```

```json
{
  "id": "det_4f9Qm2LxV7cT1bZr8KpA",
  "url": "wss://api.patchamd.com/v1/stream?token=det_4f9Qm2LxV7cT1bZr8KpA.1794340000000.…",
  "base_url": "wss://api.patchamd.com/v1/stream",
  "token": "det_4f9Qm2LxV7cT1bZr8KpA.1794340000000.…",
  "expires_at": "2026-11-10T19:53:03.114Z"
}
```

The URL works once and must be opened within 10 minutes.

## 3. Act on the decision

We POST an `amd.decided` [webhook](/docs/webhooks) to your `webhook_url` (and, for raw streams, send the same event on the socket):

```json
{ "type": "amd.decided", "data": { "detection_id": "det_…", "result": "human", "reason": "person_waiting", "at_ms": 1620, "heard": "Hello?" } }
```

| result | What it means | Typical action |
|---|---|---|
| `human` | A person answered and is waiting | Connect a rep or agent |
| `voicemail` | Voicemail greeting | Hang up, or leave a message |
| `ivr` | Phone menu, hold queue, call screening | Hang up or navigate |
| `unavailable` | Not in service, can't be completed, mailbox full or not set up | Hang up; clean the number |
| `silence` | Nobody spoke | Hang up or retry |
| `not_sure` | Could not tell, or our detector failed | **Treat as a person** |

## Timing

A person is usually connected a fraction of a second after they finish their greeting (median 0.15 s on our [benchmark](/benchmark)). Recordings are usually caught mid-greeting, a median 3.4 s after pickup. If nobody speaks the result is `silence`, and every stream reaches a decision within seconds.

## Next

- [API reference](/docs/api-reference) — REST endpoints, stream protocol, results and reasons
- [Webhooks](/docs/webhooks) — signature verification
- Machine-readable: [OpenAPI](/openapi.json), [AsyncAPI](/asyncapi.json), [llms-full.txt](/llms-full.txt)