# API: Market

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/buyer-personas` | Buyer personas (suggested from won deals, or set by a person) | `prospecting:read` |
| POST | `/v1/buyer-personas` | Add a buyer persona (titles, seniorities, departments, include and exclude keywords, a cap per account) | `prospecting:write` |
| PATCH | `/v1/buyer-personas/:id` | Edit a persona, or accept (active) or archive a suggestion | `prospecting:write` |
| GET | `/v1/buyer-personas/:id/provider-search` | The persona's recent provider searches (queued, done or failed) with the people found | `prospecting:read` |
| POST | `/v1/buyer-personas/:id/provider-search` | Queue a People Data Labs search for the persona at these accounts (it runs in the worker; needs a PDL key; results are listed only, never imported) | `prospecting:write` |
| POST | `/v1/buyer-personas/learn` | Suggest personas from the titles and deal roles of contacts on won deals (suggestions wait for a person) | `prospecting:write` |
| POST | `/v1/buyer-personas/match` | Contacts that fit the active personas inside target accounts (given ids, a lookalike run, or the default ICP's matches), with matched and skipped contacts and why | `prospecting:read` |
| GET | `/v1/lookalike-runs` | Lookalike runs (one per won deal, plus manual runs), with ranked results, matched attributes, drops and the staged segment | `prospecting:read` |
| POST | `/v1/lookalike-runs` | Queue a lookalike run from a won deal (once per deal) or from every closed-won account; results are staged as a segment for review | `prospecting:write` |
| POST | `/v1/lookalike-runs/:id/import` | Import chosen companies a provider found outside the CRM as accounts (an explicit step by a person; existing domains are skipped) (web app only) | `prospecting:write` |
| GET | `/v1/market/settings` | Tracked technologies, GTM role families, the lookalike cap and threshold, whether mail history feeds the TAM; which paid vendors are on (PredictLeads, People Data Labs) and SIG-004's off setting | `prospecting:read` |
| PUT | `/v1/market/settings` | Change the market settings (owners). Person-level visitor de-anonymization can't be turned on (founder decision 9). | `settings:write` |
| GET | `/v1/tam` | The TAM: counts by source (ICP, customer-similar, mail), segment and size, coverage gaps, the market count when a provider is set up, and the accounts with their sources (built on first view) | `prospecting:read` |
| POST | `/v1/tam/refresh` | Queue a TAM rebuild (it runs in the worker: adds new matches, removes disqualified or churned accounts and logs the changes; the market count when a provider is set up) | `prospecting:write` |

## Examples

### GET /v1/buyer-personas

Buyer personas (suggested from won deals, or set by a person)

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

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

### POST /v1/buyer-personas

Add a buyer persona (titles, seniorities, departments, include and exclude keywords, a cap per account)

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

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

### PATCH /v1/buyer-personas/$ID

Edit a persona, or accept (active) or archive a suggestion

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

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

### GET /v1/buyer-personas/$ID/provider-search

The persona's recent provider searches (queued, done or failed) with the people found

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

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

### POST /v1/buyer-personas/$ID/provider-search

Queue a People Data Labs search for the persona at these accounts (it runs in the worker; needs a PDL key; results are listed only, never imported)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/buyer-personas/${id}/provider-search`, {
  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/buyer-personas/learn

Suggest personas from the titles and deal roles of contacts on won deals (suggestions wait for a person)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/buyer-personas/learn`, {
  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/buyer-personas/match

Contacts that fit the active personas inside target accounts (given ids, a lookalike run, or the default ICP's matches), with matched and skipped contacts and why

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

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

Lookalike runs (one per won deal, plus manual runs), with ranked results, matched attributes, drops and the staged segment

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

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

### POST /v1/lookalike-runs

Queue a lookalike run from a won deal (once per deal) or from every closed-won account; results are staged as a segment for review

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

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

Tracked technologies, GTM role families, the lookalike cap and threshold, whether mail history feeds the TAM; which paid vendors are on (PredictLeads, People Data Labs) and SIG-004's off setting

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

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

### PUT /v1/market/settings

Change the market settings (owners). Person-level visitor de-anonymization can't be turned on (founder decision 9).

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

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

The TAM: counts by source (ICP, customer-similar, mail), segment and size, coverage gaps, the market count when a provider is set up, and the accounts with their sources (built on first view)

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

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

### POST /v1/tam/refresh

Queue a TAM rebuild (it runs in the worker: adds new matches, removes disqualified or churned accounts and logs the changes; the market count when a provider is set up)

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

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