# API: Plays

| Method | Path | What it does | Scope |
|---|---|---|---|
| POST | `/v1/autopilot-refills/:id/decide` | Approve (import, dedupe, enroll through every check) or reject a proposed refill | `messages:send` |
| GET | `/v1/event-plays` | Events with follow-up plays | `sequences:read` |
| POST | `/v1/event-plays` | Create an event (webinar, conference, meetup) for follow-up plays | `sequences:write` |
| GET | `/v1/event-plays/:id` | An event: its funnel (imported → companies matched → in ICP → ICP role), statuses and attendees | `sequences:read` |
| POST | `/v1/event-plays/:id/attendees` | Import (or re-import) the attendee list as CSV: email, name, company, title, status (registered, attended, no-show, speaker, booth) | `sequences:write` |
| POST | `/v1/event-plays/:id/run` | Draft the follow-up for each ICP-role person not yet handled (by status), held for the record owner | `sequences:write` |
| GET | `/v1/play-graphs` | Play graphs (journeys) | `sequences:read` |
| POST | `/v1/play-graphs` | Create a play graph (a draft): trigger, A/B, if/else, webhook, assign-owner, lookalike, enroll and end nodes | `sequences:write` |
| GET | `/v1/play-graphs/:id` | A play graph | `sequences:read` |
| PUT | `/v1/play-graphs/:id` | Save a play graph (validated; a new version) | `sequences:write` |
| GET | `/v1/play-graphs/:id/export` | Export a play graph as JSON (to import elsewhere) | `sequences:read` |
| POST | `/v1/play-graphs/:id/paste` | Paste nodes into a play (ids renumbered; links outside the pasted nodes end), optionally after a node; a new version | `sequences:write` |
| POST | `/v1/play-graphs/:id/restore` | Restore an earlier version (as a new version) | `sequences:write` |
| POST | `/v1/play-graphs/:id/run` | Run contacts through an active play (at most 100; each node's result is logged) | `sequences:write` |
| GET | `/v1/play-graphs/:id/runs` | A play's recent runs with each node's result | `sequences:read` |
| POST | `/v1/play-graphs/:id/status` | Turn a play on, pause or archive it (a play with a webhook is turned on by an organization owner) | `sequences:write` |
| POST | `/v1/play-graphs/:id/undo` | Undo the last save (the version before becomes the newest) | `sequences:write` |
| GET | `/v1/play-graphs/:id/versions` | A play's versions, newest first | `sequences:read` |
| POST | `/v1/play-graphs/import` | Import a play graph exported as JSON (a new draft) | `sequences:write` |
| POST | `/v1/plays/reactivation` | Run the reactivation play: closed-lost and dormant contacts, grounded drafts held for each owner (dry_run: who and why, nothing drafted) | `sequences:write` |
| GET | `/v1/plays/runs` | Play runs (reactivation, event) with their counts | `sequences:read` |
| GET | `/v1/plays/runs/:id` | A play run: each person (drafted or skipped, and why) and the outcomes: replies, meetings, re-opened opportunities, revived pipeline | `sequences:read` |
| GET | `/v1/sequences/:id/autopilot` | A sequence's autopilot: source, threshold, refill size, budgets (spent and left), approval, and its refills | `sequences:read` |
| PUT | `/v1/sequences/:id/autopilot` | Set a sequence's autopilot (its owner, or an organization owner; enrolling without approval is an organization owner's choice) | `messages:send` |
| POST | `/v1/sequences/:id/autopilot/refill` | Check for a refill now (sizes it, checks budgets, searches, proposes or enrolls) | `messages:send` |
| GET | `/v1/settings/plays` | Play settings: the weekly reactivation play and its cold threshold | `sequences:read` |
| PUT | `/v1/settings/plays` | Change play settings (owners, signed in) (web app only) | `settings:write` |

## Examples

### POST /v1/autopilot-refills/$ID/decide

Approve (import, dedupe, enroll through every check) or reject a proposed refill

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

```js
const res = await fetch(`https://api.closefinch.com/v1/autopilot-refills/${id}/decide`, {
  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/event-plays

Events with follow-up plays

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

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

### POST /v1/event-plays

Create an event (webinar, conference, meetup) for follow-up plays

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

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

An event: its funnel (imported → companies matched → in ICP → ICP role), statuses and attendees

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

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

### POST /v1/event-plays/$ID/attendees

Import (or re-import) the attendee list as CSV: email, name, company, title, status (registered, attended, no-show, speaker, booth)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/event-plays/${id}/attendees`, {
  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/event-plays/$ID/run

Draft the follow-up for each ICP-role person not yet handled (by status), held for the record owner

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

```js
const res = await fetch(`https://api.closefinch.com/v1/event-plays/${id}/run`, {
  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/play-graphs

Play graphs (journeys)

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

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

### POST /v1/play-graphs

Create a play graph (a draft): trigger, A/B, if/else, webhook, assign-owner, lookalike, enroll and end nodes

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

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

A play graph

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

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

### PUT /v1/play-graphs/$ID

Save a play graph (validated; a new version)

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

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

Export a play graph as JSON (to import elsewhere)

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

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

### POST /v1/play-graphs/$ID/paste

Paste nodes into a play (ids renumbered; links outside the pasted nodes end), optionally after a node; a new version

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

```js
const res = await fetch(`https://api.closefinch.com/v1/play-graphs/${id}/paste`, {
  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/play-graphs/$ID/restore

Restore an earlier version (as a new version)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/play-graphs/${id}/restore`, {
  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/play-graphs/$ID/run

Run contacts through an active play (at most 100; each node's result is logged)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/play-graphs/${id}/run`, {
  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/play-graphs/$ID/runs

A play's recent runs with each node's result

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

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

### POST /v1/play-graphs/$ID/status

Turn a play on, pause or archive it (a play with a webhook is turned on by an organization owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/play-graphs/${id}/status`, {
  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/play-graphs/$ID/undo

Undo the last save (the version before becomes the newest)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/play-graphs/${id}/undo`, {
  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/play-graphs/$ID/versions

A play's versions, newest first

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

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

### POST /v1/play-graphs/import

Import a play graph exported as JSON (a new draft)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/play-graphs/import`, {
  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/plays/reactivation

Run the reactivation play: closed-lost and dormant contacts, grounded drafts held for each owner (dry_run: who and why, nothing drafted)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/plays/reactivation`, {
  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/plays/runs

Play runs (reactivation, event) with their counts

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

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

### GET /v1/plays/runs/$ID

A play run: each person (drafted or skipped, and why) and the outcomes: replies, meetings, re-opened opportunities, revived pipeline

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

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

### GET /v1/sequences/$ID/autopilot

A sequence's autopilot: source, threshold, refill size, budgets (spent and left), approval, and its refills

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

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

### PUT /v1/sequences/$ID/autopilot

Set a sequence's autopilot (its owner, or an organization owner; enrolling without approval is an organization owner's choice)

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

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

Check for a refill now (sizes it, checks budgets, searches, proposes or enrolls)

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

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

Play settings: the weekly reactivation play and its cold threshold

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

```js
const res = await fetch(`https://api.closefinch.com/v1/settings/plays`, {
  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).