# API: Signals

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/accounts/:id/signals` | An account's signal fields, the score's breakdown and its dated why-now evidence | `accounts:read` |
| GET | `/v1/community/hits` | Detections: people and companies on event lists, podcast guests, reviews and GitHub activity, with the match and the quote | `signals:read` |
| POST | `/v1/community/hits/:id/met` | Mark (or unmark) a person on an event list as met: they go on the follow-up list | `signals:write` |
| GET | `/v1/community/podcast-search` | Find podcast feeds by name (the free iTunes Search API; your words are sent to Apple) | `signals:read` |
| GET | `/v1/community/review-sites` | Review sites we checked: terms URL, date checked, allowed or not, and why | `signals:read` |
| GET | `/v1/community/sources` | Registered community sources (events, podcasts, review sources with their terms status, GitHub repositories) with detection counts | `signals:read` |
| POST | `/v1/community/sources` | Register a source: a public event page (or a CSV-only event), a podcast RSS feed, a review page whose terms allow reading (or a paste-only review source), or a GitHub repository | `signals:write` |
| DELETE | `/v1/community/sources/:id` | Remove a source and its detections (signals already fired stay) | `signals:write` |
| PATCH | `/v1/community/sources/:id` | Pause or resume a source, rename it, or record a review site's terms check (terms URL, allowed yes/no, note) | `signals:write` |
| POST | `/v1/community/sources/:id/csv` | Import an event's attendee, speaker or sponsor list (CSV), matched by email, then name and company, then company | `signals:write` |
| POST | `/v1/community/sources/:id/poll` | Check a source now, in the background (one community job at a time per organization; once a minute per source). Poll the sources list: `pending` drops to 0 when it's done | `signals:write` |
| POST | `/v1/community/sources/:id/reviews` | Paste reviews or import them as CSV; they're analysed in the background (named pains with the reviewer's words, role, company size, us or a competitor). Poll the sources list until `pending` is 0 | `signals:write` |
| GET | `/v1/signal-events` | The feed: signals across monitors, newest first (unread = new) | `signals:read` |
| POST | `/v1/signal-events/:id/:action` | Mark a signal seen, dismiss it (it stops counting toward the score) or restore it | `signals:write` |
| POST | `/v1/signal-events/seen` | Mark every new signal seen | `signals:write` |
| GET | `/v1/signal-presets` | Built-in monitors you can turn on with one click, and the cadence choices | `signals:read` |
| POST | `/v1/signal-presets/:key/enable` | Turn on a built-in monitor (presets that read the web take an audience: a list, an ICP or chosen accounts) | `signals:write` |
| GET | `/v1/signals` | Monitors (the All view): schedule, status, last and next run, activity in the last 7 and 30 days | `signals:read` |
| POST | `/v1/signals` | Create a monitor (a draft: test it, then turn it on) | `signals:write` |
| DELETE | `/v1/signals/:id` | Delete a monitor and the signals it found (owner) | `settings:write` |
| GET | `/v1/signals/:id` | One monitor | `signals:read` |
| PATCH | `/v1/signals/:id` | Edit a monitor (rule, strength, schedule, audience) | `signals:write` |
| POST | `/v1/signals/:id/run` | Run a monitor now (also a paused or draft one). CRM monitors run at once; news monitors are queued. | `signals:write` |
| POST | `/v1/signals/:id/state` | Turn a monitor on or pause it | `signals:write` |
| POST | `/v1/signals/:id/test` | Dry run: what the monitor would find now (saves nothing; public-event monitors check up to 5 accounts) | `signals:write` |
| POST | `/v1/signals/compile` | Turn a plain-English description into a monitor rule you can review and edit (nothing is saved) | `signals:write` |
| GET | `/v1/target-accounts` | Accounts with their score, status, signals and latest signal, sortable and filterable | `accounts:read` |

## Examples

### GET /v1/accounts/$ID/signals

An account's signal fields, the score's breakdown and its dated why-now evidence

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

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

### GET /v1/community/hits

Detections: people and companies on event lists, podcast guests, reviews and GitHub activity, with the match and the quote

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

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

### POST /v1/community/hits/$ID/met

Mark (or unmark) a person on an event list as met: they go on the follow-up list

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

```js
const res = await fetch(`https://api.closefinch.com/v1/community/hits/${id}/met`, {
  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/community/podcast-search

Find podcast feeds by name (the free iTunes Search API; your words are sent to Apple)

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

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

### GET /v1/community/review-sites

Review sites we checked: terms URL, date checked, allowed or not, and why

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

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

### GET /v1/community/sources

Registered community sources (events, podcasts, review sources with their terms status, GitHub repositories) with detection counts

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

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

### POST /v1/community/sources

Register a source: a public event page (or a CSV-only event), a podcast RSS feed, a review page whose terms allow reading (or a paste-only review source), or a GitHub repository

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

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

Remove a source and its detections (signals already fired stay)

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

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

### PATCH /v1/community/sources/$ID

Pause or resume a source, rename it, or record a review site's terms check (terms URL, allowed yes/no, note)

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

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

Import an event's attendee, speaker or sponsor list (CSV), matched by email, then name and company, then company

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

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

Check a source now, in the background (one community job at a time per organization; once a minute per source). Poll the sources list: `pending` drops to 0 when it's done

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

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

Paste reviews or import them as CSV; they're analysed in the background (named pains with the reviewer's words, role, company size, us or a competitor). Poll the sources list until `pending` is 0

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

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

The feed: signals across monitors, newest first (unread = new)

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

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

### POST /v1/signal-events/$ID/$ACTION

Mark a signal seen, dismiss it (it stops counting toward the score) or restore it

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

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

Mark every new signal seen

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

```js
const res = await fetch(`https://api.closefinch.com/v1/signal-events/seen`, {
  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/signal-presets

Built-in monitors you can turn on with one click, and the cadence choices

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

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

### POST /v1/signal-presets/$KEY/enable

Turn on a built-in monitor (presets that read the web take an audience: a list, an ICP or chosen accounts)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/signal-presets/${key}/enable`, {
  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/signals

Monitors (the All view): schedule, status, last and next run, activity in the last 7 and 30 days

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

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

### POST /v1/signals

Create a monitor (a draft: test it, then turn it on)

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

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

Delete a monitor and the signals it found (owner)

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

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

### GET /v1/signals/$ID

One monitor

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

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

### PATCH /v1/signals/$ID

Edit a monitor (rule, strength, schedule, audience)

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

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

Run a monitor now (also a paused or draft one). CRM monitors run at once; news monitors are queued.

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

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

### POST /v1/signals/$ID/state

Turn a monitor on or pause it

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

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

Dry run: what the monitor would find now (saves nothing; public-event monitors check up to 5 accounts)

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

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

Turn a plain-English description into a monitor rule you can review and edit (nothing is saved)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/signals/compile`, {
  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/target-accounts

Accounts with their score, status, signals and latest signal, sortable and filterable

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

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