# API: Voice calls

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/voice/calls/:id/actions` | What the voice agent did for the caller on a call: texts, booking confirmations, payment links, catalog answers, price checks and card redactions | `calls:read` |
| GET | `/v1/voice/flows/calls` | Calls the AI voice agent handled (newest first): who, routing, time to answer, outcome | `settings:read` |
| GET | `/v1/voice/flows/calls/:id` | One call: the routing decision, time to answer and to the first audio, disclosure, screening, transcript (withheld when the caller objected to recording), recording, tools, message, booking, outcome | `transcripts:read` |
| GET | `/v1/voice/flows/routing` | Inbound routing per number, with who would answer right now | `settings:read` |
| PUT | `/v1/voice/flows/routing` | Set how a number is answered (owner): AI always, or business hours to a ring group (all rung at once) with overflow to the AI after N seconds or when nobody is available; after hours and holidays the AI answers. Versioned | `settings:write` |
| POST | `/v1/voice/flows/screening-preview` | Check a screening line and hear what a screener would be told | `settings:read` |
| GET | `/v1/voice/flows/settings` | Call-flow settings: outbound AI calls (off by default), speed-to-lead attempts, spacing and target, the screening line and its silence timeout, recording | `settings:read` |
| PUT | `/v1/voice/flows/settings` | Change the call-flow settings (owner). Turning outbound AI calls on covers callbacks to people who consented on a form only; the screening line can be reworded, never made to hide that it's an AI | `settings:write` |
| GET | `/v1/voice/flows/speed-to-lead` | Speed-to-lead: submit-to-dial times (p50/p95) against the target, inbound time to answer, and recent leads with their attempts and outcomes | `settings:read` |

## Examples

### GET /v1/voice/calls/$ID/actions

What the voice agent did for the caller on a call: texts, booking confirmations, payment links, catalog answers, price checks and card redactions

```bash
curl -s "https://api.closefinch.com/v1/voice/calls/$ID/actions" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/calls/${id}/actions`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/voice/flows/calls

Calls the AI voice agent handled (newest first): who, routing, time to answer, outcome

```bash
curl -s "https://api.closefinch.com/v1/voice/flows/calls" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/calls`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/voice/flows/calls/$ID

One call: the routing decision, time to answer and to the first audio, disclosure, screening, transcript (withheld when the caller objected to recording), recording, tools, message, booking, outcome

```bash
curl -s "https://api.closefinch.com/v1/voice/flows/calls/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/calls/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/voice/flows/routing

Inbound routing per number, with who would answer right now

```bash
curl -s "https://api.closefinch.com/v1/voice/flows/routing" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/routing`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### PUT /v1/voice/flows/routing

Set how a number is answered (owner): AI always, or business hours to a ring group (all rung at once) with overflow to the AI after N seconds or when nobody is available; after hours and holidays the AI answers. Versioned

```bash
curl -s -X PUT "https://api.closefinch.com/v1/voice/flows/routing" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/routing`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/voice/flows/screening-preview

Check a screening line and hear what a screener would be told

```bash
curl -s -X POST "https://api.closefinch.com/v1/voice/flows/screening-preview" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/screening-preview`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/voice/flows/settings

Call-flow settings: outbound AI calls (off by default), speed-to-lead attempts, spacing and target, the screening line and its silence timeout, recording

```bash
curl -s "https://api.closefinch.com/v1/voice/flows/settings" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/settings`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### PUT /v1/voice/flows/settings

Change the call-flow settings (owner). Turning outbound AI calls on covers callbacks to people who consented on a form only; the screening line can be reworded, never made to hide that it's an AI

```bash
curl -s -X PUT "https://api.closefinch.com/v1/voice/flows/settings" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/settings`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/voice/flows/speed-to-lead

Speed-to-lead: submit-to-dial times (p50/p95) against the target, inbound time to answer, and recent leads with their attempts and outcomes

```bash
curl -s "https://api.closefinch.com/v1/voice/flows/speed-to-lead" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/flows/speed-to-lead`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).