API reference
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
curl -s "https://api.closefinch.com/v1/social/engagers" \
-H "Authorization: Bearer $RA_API_KEY"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
curl -s "https://api.closefinch.com/v1/social/hooks/$ID" \
-H "Authorization: Bearer $RA_API_KEY"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
curl -s "https://api.closefinch.com/v1/social/lead-magnets" \
-H "Authorization: Bearer $RA_API_KEY"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
curl -s "https://api.closefinch.com/v1/social/lead-magnets/$ID/replies" \
-H "Authorization: Bearer $RA_API_KEY"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)
curl -s "https://api.closefinch.com/v1/social/likes" \
-H "Authorization: Bearer $RA_API_KEY"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)
curl -s "https://api.closefinch.com/v1/social/personas/suggested" \
-H "Authorization: Bearer $RA_API_KEY"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)
curl -s "https://api.closefinch.com/v1/social/review" \
-H "Authorization: Bearer $RA_API_KEY"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)
curl -s "https://api.closefinch.com/v1/social/settings" \
-H "Authorization: Bearer $RA_API_KEY"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
curl -s "https://api.closefinch.com/v1/social/status" \
-H "Authorization: Bearer $RA_API_KEY"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
curl -s "https://api.closefinch.com/v1/social/watches" \
-H "Authorization: Bearer $RA_API_KEY"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. All resources: API reference.