# API: Voice campaigns

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/voice/campaigns` | Voice campaigns and call triggers, newest first, each with its live progress (people by status, dials, connections, voicemails, goals, opt-outs, spend) | `calls:read` |
| POST | `/v1/voice/campaigns` | Create a voice campaign or call trigger (owner), as a draft: audience, voice agent, window in the callee's time zone, pacing, retries, goals, AMD and the voicemail sequencer | `settings:write` |
| GET | `/v1/voice/campaigns/:id` | One campaign: settings, live progress, people (number masked) and recent attempts with outcome, goal and the voicemail left (its text and announcement version) | `calls:read` |
| PATCH | `/v1/voice/campaigns/:id` | Change a campaign (owner; send the version you edited) | `settings:write` |
| POST | `/v1/voice/campaigns/:id/launch` | Launch a campaign (owner, from the app): the audience is enrolled and calls go out within its window and pacing, each through the calling gate (web app only) | `messages:send` |
| POST | `/v1/voice/campaigns/:id/pause` | Pause a campaign (owner) | `settings:write` |
| POST | `/v1/voice/campaigns/:id/resume` | Resume a campaign (owner) | `messages:send` |
| POST | `/v1/voice/campaigns/:id/stop` | Stop a campaign (owner): waiting people are stopped; calls already ringing finish | `settings:write` |
| GET | `/v1/voice/campaigns/settings` | Campaign settings: the voicemail drop on speed-to-lead calls (off by default) and missed-meeting detection | `settings:read` |
| PUT | `/v1/voice/campaigns/settings` | Change the campaign settings (owner) | `settings:write` |
| POST | `/v1/voice/campaigns/voicemail-preview` | Check a voicemail wording and hear it as it would be left: the AI voicemail announcement (business, callback number) first | `calls:read` |

## Examples

### GET /v1/voice/campaigns

Voice campaigns and call triggers, newest first, each with its live progress (people by status, dials, connections, voicemails, goals, opt-outs, spend)

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

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

### POST /v1/voice/campaigns

Create a voice campaign or call trigger (owner), as a draft: audience, voice agent, window in the callee's time zone, pacing, retries, goals, AMD and the voicemail sequencer

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

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/campaigns`, {
  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/campaigns/$ID

One campaign: settings, live progress, people (number masked) and recent attempts with outcome, goal and the voicemail left (its text and announcement version)

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

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

### PATCH /v1/voice/campaigns/$ID

Change a campaign (owner; send the version you edited)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/campaigns/${id}`, {
  method: "PATCH",
  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/campaigns/$ID/pause

Pause a campaign (owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/campaigns/${id}/pause`, {
  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();
```

### POST /v1/voice/campaigns/$ID/resume

Resume a campaign (owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/campaigns/${id}/resume`, {
  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();
```

### POST /v1/voice/campaigns/$ID/stop

Stop a campaign (owner): waiting people are stopped; calls already ringing finish

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

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/campaigns/${id}/stop`, {
  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/campaigns/settings

Campaign settings: the voicemail drop on speed-to-lead calls (off by default) and missed-meeting detection

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

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

### PUT /v1/voice/campaigns/settings

Change the campaign settings (owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/campaigns/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();
```

### POST /v1/voice/campaigns/voicemail-preview

Check a voicemail wording and hear it as it would be left: the AI voicemail announcement (business, callback number) first

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

```js
const res = await fetch(`https://api.closefinch.com/v1/voice/campaigns/voicemail-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();
```

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).