# API: Social signals

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/social/engagers` | People who reacted, commented, followed or viewed, with their ICP check and CRM match | `signals:read` |
| GET | `/v1/social/hooks/:id` | A contact's latest relevant recent post (the opener for outreach), if any | `signals:read` |
| GET | `/v1/social/lead-magnets` | Comment-a-keyword lead magnets | `signals:read` |
| POST | `/v1/social/lead-magnets` | Draft a lead magnet: post copy asking for a keyword (drafted by AI unless given), the resource and its delivery channel (web app only) | `signals:write` |
| POST | `/v1/social/lead-magnets/:id/close` | Stop reading and delivering for a lead magnet (web app only) | `signals:write` |
| POST | `/v1/social/lead-magnets/:id/decision` | Approve the post (optionally edited; it's posted from your LinkedIn account) or reject it (web app only) | `signals:write` |
| GET | `/v1/social/lead-magnets/:id/replies` | Each comment: keyword match, genuine/bot/competitor/low-fit with reasons, saved or not, and delivery | `signals:read` |
| POST | `/v1/social/lead-magnets/:id/replies/:rid/send` | Send a held email delivery yourself (the magnet's owner): your own approved email, through your send rules, once (web app only) | `messages:send` |
| POST | `/v1/social/lead-magnets/:id/sync` | Read new comments now, classify them, save genuine ones and deliver the resource (within limits) (web app only) | `messages:send` |
| GET | `/v1/social/likes` | Likes waiting for your approval (proposed from the social review queue) | `signals:read` |
| POST | `/v1/social/likes/:id` | Approve or reject a like waiting for you (it's done from your LinkedIn account; comments are decided under LinkedIn comments) (web app only) | `signals:write` |
| GET | `/v1/social/personas/suggested` | Persona ideas from the titles of contacts on won deals (normalized) | `signals:read` |
| GET | `/v1/social/review` | The social review queue: stated needs, recent posters and engagers waiting for a person (skipped ones with why) | `signals:read` |
| POST | `/v1/social/review/:id` | Approve (links the CRM contact, or saves a new lead) or reject a queued person (web app only) | `signals:write` |
| POST | `/v1/social/review/:id/engage` | Ask for a like or a drafted comment on a recent poster's post before outreach (waits for its sender's approval) (web app only) | `signals:write` |
| GET | `/v1/social/settings` | Social signals: the organization switch, keywords and problems, thresholds, and whether X and Reddit are connected (never the keys) | `settings:read` |
| PUT | `/v1/social/settings` | Turn social signals on or off, set keywords, problems and thresholds, and the organization's own X token and Reddit app (owners, signed in; stored encrypted) (web app only) | `settings:write` |
| GET | `/v1/social/status` | What social signals can do for you here (Unipile account, Premium for profile viewers, company pages, X, Reddit) and why not | `settings:read` |
| POST | `/v1/social/viewers` | Import the profile viewers LinkedIn shows you (anonymous viewers are excluded; without Premium the list is marked incomplete) (web app only) | `signals:write` |
| GET | `/v1/social/watches` | Watched posts, authors, keyword searches, company pages, recent-poster searches and listening queries | `signals:read` |
| POST | `/v1/social/watches` | Watch a LinkedIn post or author, a keyword search, a company page (admins only), recent posters, or listen on LinkedIn, X and Reddit (web app only) | `signals:write` |
| DELETE | `/v1/social/watches/:id` | Delete a watch and what it read (web app only) | `signals:write` |
| PATCH | `/v1/social/watches/:id` | Pause or resume a watch (web app only) | `signals:write` |
| POST | `/v1/social/watches/:id/run` | Read a watch now (within its LinkedIn account's daily reads) (web app only) | `signals:write` |

## Examples

### GET /v1/social/engagers

People who reacted, commented, followed or viewed, with their ICP check and CRM match

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

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

### GET /v1/social/hooks/$ID

A contact's latest relevant recent post (the opener for outreach), if any

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

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

### GET /v1/social/lead-magnets

Comment-a-keyword lead magnets

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

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

### GET /v1/social/lead-magnets/$ID/replies

Each comment: keyword match, genuine/bot/competitor/low-fit with reasons, saved or not, and delivery

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

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

### GET /v1/social/likes

Likes waiting for your approval (proposed from the social review queue)

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

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

### GET /v1/social/personas/suggested

Persona ideas from the titles of contacts on won deals (normalized)

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

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

### GET /v1/social/review

The social review queue: stated needs, recent posters and engagers waiting for a person (skipped ones with why)

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

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

### GET /v1/social/settings

Social signals: the organization switch, keywords and problems, thresholds, and whether X and Reddit are connected (never the keys)

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

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

### GET /v1/social/status

What social signals can do for you here (Unipile account, Premium for profile viewers, company pages, X, Reddit) and why not

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

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

### GET /v1/social/watches

Watched posts, authors, keyword searches, company pages, recent-poster searches and listening queries

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

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