# API: Prospecting

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/accounts/:id/icp` | Whether an account fits an ICP (the default unless icp_id), and why | `accounts:read` |
| DELETE | `/v1/event-invites/:id` | Remove a candidate who hasn't been invited | `prospecting:write` |
| POST | `/v1/event-invites/:id/confirm-location` | Confirm that a candidate whose location only shares the city name is in the event's city (web app only) | `prospecting:write` |
| POST | `/v1/event-invites/:id/rsvp` | Record an RSVP (accepts beyond capacity go to the waitlist) (web app only) | `prospecting:write` |
| GET | `/v1/icps` | Ideal customer profiles | `prospecting:read` |
| POST | `/v1/icps` | Create an ICP (owner): may-contact rules, must-not-contact rules and automatic exclusions (customers, partners, open deals) | `settings:write` |
| GET | `/v1/icps/:id` | One ICP | `prospecting:read` |
| PUT | `/v1/icps/:id` | Replace an ICP's rules (owner) | `settings:write` |
| POST | `/v1/icps/:id/archive` | Archive an ICP (owner; its must-not rules stop applying) | `settings:write` |
| DELETE | `/v1/icps/:id/overrides/:account` | Remove an override (owner) | `settings:write` |
| PUT | `/v1/icps/:id/overrides/:account` | Let an automatically excluded account back into prospecting, with a reason (owner, from the app; must-not rules still hold) (web app only) | `settings:write` |
| GET | `/v1/icps/:id/preview` | Accounts that fit, and how many each rule removes | `prospecting:read` |
| GET | `/v1/prospect-events` | Event plays, soonest last | `prospecting:read` |
| POST | `/v1/prospect-events` | Create an event play (dinner, coffee or conference) with a city, date, capacity and host (web app only) | `prospecting:write` |
| GET | `/v1/prospect-events/:id` | An event: candidates, invitations and RSVPs, with seats taken against capacity | `prospecting:read` |
| POST | `/v1/prospect-events/:id/attendees` | Conference mode: import an attendee, speaker or sponsor list (CSV), matched to CRM people by email, then name and company; the rest become leads | `prospecting:write` |
| POST | `/v1/prospect-events/:id/candidates` | Select candidates in the event's city (and its ICP), leaving out do-not-contact, must-not-contact, recently touched accounts and customers | `prospecting:write` |
| POST | `/v1/prospect-events/:id/invite` | Draft invitations for candidates (all, or chosen ones; 50 at a time) in the background: each waits for the host's approval in their inbox (web app only) | `prospecting:write` |
| GET | `/v1/prospect-plays` | Plays: agent-proposed ones waiting for a person, then accepted ones | `sequences:read` |
| POST | `/v1/prospect-plays` | Add your own play (owner) | `settings:write` |
| GET | `/v1/prospect-plays/:id` | One play with its versions | `sequences:read` |
| PUT | `/v1/prospect-plays/:id` | Edit one play's audience, trigger, offer or rationale: a new version of this play only (owner) | `settings:write` |
| POST | `/v1/prospect-plays/:id/accept` | Accept a proposed play, as is or with edits (owner) | `settings:write` |
| GET | `/v1/prospect-plays/:id/preview` | Who in the CRM a play's audience reaches now (customers, partners and open deals left out) | `sequences:read` |
| POST | `/v1/prospect-plays/:id/reject` | Reject a proposed play (owner; it isn't proposed again) | `settings:write` |
| POST | `/v1/prospect-plays/propose` | Propose plays from your site, profile and won deals (owner; a play already known isn't proposed again) | `settings:write` |
| GET | `/v1/prospecting/caps` | The organization's daily caps on recruiting emails (across goals) and event invitations (across events) | `prospecting:read` |
| PUT | `/v1/prospecting/caps` | Set the organization's daily caps (owner) | `settings:write` |
| GET | `/v1/qualify` | Qualification runs, newest first | `prospecting:read` |
| POST | `/v1/qualify` | Set up a qualification run: fit questions over a list of accounts (or chosen accounts). Returns the cost estimate; nothing runs until it's started | `prospecting:write` |
| GET | `/v1/qualify/:id` | A run: its questions, status, counts per verdict and the cost estimate for re-running stale rows | `prospecting:read` |
| PUT | `/v1/qualify/:id/questions` | Edit the questions (and budget): answered rows become stale until re-run | `prospecting:write` |
| GET | `/v1/qualify/:id/rows` | Rows with a verdict per question (reason and sources) and the roll-up; filter and sort by verdict | `prospecting:read` |
| POST | `/v1/qualify/:id/rows/:row/rerun` | Re-run one row | `prospecting:write` |
| POST | `/v1/qualify/:id/save-list` | Save only the passes as a static list of accounts | `prospecting:write` |
| POST | `/v1/qualify/:id/start` | Run it in the background: every row, or only rows not answered for the current questions | `prospecting:write` |
| POST | `/v1/qualify/:id/stop` | Stop a run (rows not reached stay pending) | `prospecting:write` |
| POST | `/v1/recruit-candidates/:id/stage` | Move a candidate (replied, committed, active or declined with their reason, quoted from their reply when there is one) (web app only) | `prospecting:write` |
| GET | `/v1/recruit-goals` | Recruiting goals with live progress (active out of N) | `prospecting:read` |
| POST | `/v1/recruit-goals` | Start recruiting: a target number of active design partners, what counts as active, outreach caps and a budget. Emails go from the sender's mailbox only when they approve each one (web app only) | `prospecting:write` |
| GET | `/v1/recruit-goals/:id` | A goal: progress, every candidate's stage and the learnings from declines (quoted, with sources) | `prospecting:read` |
| PATCH | `/v1/recruit-goals/:id` | Change the target, caps, budget or pitch | `prospecting:write` |
| POST | `/v1/recruit-goals/:id/:state` | Stop (withdrawing drafts nobody approved yet) or resume a goal (web app only) | `prospecting:write` |
| POST | `/v1/recruit-goals/:id/next` | Propose the next batch now (in the background) | `prospecting:write` |
| GET | `/v1/segments` | Segments (lists with a grouping, an owner and a status: staged ones wait for approval) | `prospecting:read` |
| POST | `/v1/segments` | Create a segment (staged for approval unless live: true from a person) | `prospecting:write` |
| POST | `/v1/segments/:id/approve` | Approve a staged segment (a person, from the app) (web app only) | `prospecting:write` |
| GET | `/v1/segments/:id/history` | Who added or removed each member, when and why | `prospecting:read` |
| POST | `/v1/segments/:id/members` | Add (with a reason each) or remove segment members; adding twice changes nothing | `prospecting:write` |
| POST | `/v1/segments/build` | Build staged segments from an ICP's matches, grouped by territory, owner or industry | `prospecting:write` |
| GET | `/v1/waitlist` | Signups ranked, each with its reason and evidence (ineligible ones say why) | `prospecting:read` |
| POST | `/v1/waitlist/import` | Import signups (CSV, rows or a CRM list of contacts or leads): deduplicated by email, each linked to its contact or lead or creating a lead, then ranked | `prospecting:write` |
| POST | `/v1/waitlist/rank` | Re-rank every signup (in the background) | `prospecting:write` |

## Examples

### GET /v1/accounts/$ID/icp

Whether an account fits an ICP (the default unless icp_id), and why

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

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

### DELETE /v1/event-invites/$ID

Remove a candidate who hasn't been invited

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

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

### GET /v1/icps

Ideal customer profiles

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

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

### POST /v1/icps

Create an ICP (owner): may-contact rules, must-not-contact rules and automatic exclusions (customers, partners, open deals)

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

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

One ICP

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

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

### PUT /v1/icps/$ID

Replace an ICP's rules (owner)

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

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

### POST /v1/icps/$ID/archive

Archive an ICP (owner; its must-not rules stop applying)

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

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

### DELETE /v1/icps/$ID/overrides/$ACCOUNT

Remove an override (owner)

```bash
curl -s -X DELETE "https://api.closefinch.com/v1/icps/$ID/overrides/$ACCOUNT" \
  -H "Authorization: Bearer $RA_API_KEY"
```

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

### GET /v1/icps/$ID/preview

Accounts that fit, and how many each rule removes

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

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

### GET /v1/prospect-events

Event plays, soonest last

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

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

### GET /v1/prospect-events/$ID

An event: candidates, invitations and RSVPs, with seats taken against capacity

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

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

### POST /v1/prospect-events/$ID/attendees

Conference mode: import an attendee, speaker or sponsor list (CSV), matched to CRM people by email, then name and company; the rest become leads

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

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

Select candidates in the event's city (and its ICP), leaving out do-not-contact, must-not-contact, recently touched accounts and customers

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

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

Plays: agent-proposed ones waiting for a person, then accepted ones

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

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

### POST /v1/prospect-plays

Add your own play (owner)

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

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

One play with its versions

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

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

### PUT /v1/prospect-plays/$ID

Edit one play's audience, trigger, offer or rationale: a new version of this play only (owner)

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

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

### POST /v1/prospect-plays/$ID/accept

Accept a proposed play, as is or with edits (owner)

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

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

Who in the CRM a play's audience reaches now (customers, partners and open deals left out)

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

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

### POST /v1/prospect-plays/$ID/reject

Reject a proposed play (owner; it isn't proposed again)

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

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

Propose plays from your site, profile and won deals (owner; a play already known isn't proposed again)

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

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

The organization's daily caps on recruiting emails (across goals) and event invitations (across events)

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

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

### PUT /v1/prospecting/caps

Set the organization's daily caps (owner)

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

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

Qualification runs, newest first

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

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

### POST /v1/qualify

Set up a qualification run: fit questions over a list of accounts (or chosen accounts). Returns the cost estimate; nothing runs until it's started

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

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

A run: its questions, status, counts per verdict and the cost estimate for re-running stale rows

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

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

### PUT /v1/qualify/$ID/questions

Edit the questions (and budget): answered rows become stale until re-run

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

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

Rows with a verdict per question (reason and sources) and the roll-up; filter and sort by verdict

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

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

### POST /v1/qualify/$ID/rows/$ROW/rerun

Re-run one row

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

```js
const res = await fetch(`https://api.closefinch.com/v1/qualify/${id}/rows/${row}/rerun`, {
  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/qualify/$ID/save-list

Save only the passes as a static list of accounts

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

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

Run it in the background: every row, or only rows not answered for the current questions

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

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

Stop a run (rows not reached stay pending)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/qualify/${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/recruit-goals

Recruiting goals with live progress (active out of N)

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

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

### GET /v1/recruit-goals/$ID

A goal: progress, every candidate's stage and the learnings from declines (quoted, with sources)

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

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

### PATCH /v1/recruit-goals/$ID

Change the target, caps, budget or pitch

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

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

Propose the next batch now (in the background)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/recruit-goals/${id}/next`, {
  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/segments

Segments (lists with a grouping, an owner and a status: staged ones wait for approval)

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

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

### POST /v1/segments

Create a segment (staged for approval unless live: true from a person)

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

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

Who added or removed each member, when and why

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

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

### POST /v1/segments/$ID/members

Add (with a reason each) or remove segment members; adding twice changes nothing

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

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

Build staged segments from an ICP's matches, grouped by territory, owner or industry

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

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

Signups ranked, each with its reason and evidence (ineligible ones say why)

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

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

### POST /v1/waitlist/import

Import signups (CSV, rows or a CRM list of contacts or leads): deduplicated by email, each linked to its contact or lead or creating a lead, then ranked

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

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

Re-rank every signup (in the background)

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

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