API reference

Sales (experimental)

Plays, prospects, drafts and threads. The API never sends or approves.

Experimental. The Sales API is public but early. Paths and shapes can change without a new API version. Watch the changelog.

Overview

Sales AI finds prospects, writes outreach emails and keeps the threads. These endpoints read its plays, prospects, drafts and threads, start a run, and edit or skip drafts.

The API never sends an email and never approves a draft. Every draft waits for a person to approve it in Finn.

Base URL: https://api.hirefinn.ai/api/v1. Auth: Authorization: Bearer finn_live_.... See authentication.

Scopes: reads need sales:read, writes need sales:write. See scopes.

Objects come from the Sales AI service as they are, with camelCase keys. Lists use next_cursor and has_more.

Endpoints

Method	Path	Scope	What it does
`GET`	`/sales/plays`	`sales:read`	Every play. One page; `next_cursor` is always `null`.
`GET`	`/sales/plays/{slug}/runs`	`sales:read`	A play's latest runs, newest first. Up to `limit`.
`GET`	`/sales/plays/{slug}/prospects`	`sales:read`	The people a play found. Filters: `country`, `email_status`.
`POST`	`/sales/plays/{slug}/run`	`sales:write`	Queue a run of the play. Answers `202`.
`GET`	`/sales/drafts`	`sales:read`	Email drafts, newest first. Filters: `status`, `kind`, `play`.
`PATCH`	`/sales/drafts/{id}`	`sales:write`	Replace a draft's `subject` and `body`. It still waits for approval.
`POST`	`/sales/drafts/{id}/skip`	`sales:write`	Mark a draft skipped, with an optional `reason`. It is never sent.
`GET`	`/sales/threads`	`sales:read`	Email threads with prospects, latest first. Filters: `label`, `play`.
`GET`	`/sales/threads/{id}`	`sales:read`	One thread and its messages.

The Sales API allows 300 reads and 60 writes per minute per key.

Example: fix a draft before a person approves it

List the drafts that wait for approval:

curl "https://api.hirefinn.ai/api/v1/sales/drafts?status=draft&limit=20" \
  -H "Authorization: Bearer $FINN_API_KEY"

Replace one draft's subject and body:

curl -X PATCH https://api.hirefinn.ai/api/v1/sales/drafts/48213 \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Quick question about your Q1 hiring",
    "body": "Hi Priya,\n\nSaw you are hiring three SDRs. Would a 15-minute call next week help?\n\nThanks,\nSam"
  }'

The answer is the edited draft. It stays in the approval queue. A person approves and sends it in Finn, or you skip it:

curl -X POST https://api.hirefinn.ai/api/v1/sales/drafts/48213/skip \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Already in touch by phone" }'