docs sourcing
Seen register and lists
The shared contacted list, statuses, tags, and saved lists.
The seen register is your workspace's memory of people: everyone you have been shown, shortlisted, contacted, or rejected. Sourcing and outreach share it, so a guided run never pays to fetch someone you already have, and outreach never contacts someone twice. Each customer has its own.
Statuses
| Status | Set by | Effect |
|---|---|---|
seen | A guided run delivering the person, unless mark_seen is false | Guided runs skip them; raw search marks them already_seen |
shortlisted | You | Same |
contacted | Enrolling the person in a sequence | Same, and enrollment skips them unless you say otherwise |
rejected | You | Same |
do_not_contact | A negative reply, or a suppression | Skipped everywhere |
Raw search does not drop seen people by default: it returns them with already_seen: true, and drops them only with exclude_seen: true. Guided runs skip them unless the intent sets exclude.seen or exclude.contacted to false.
Write and check
POST /v1/seen adds or updates up to 1000 people. Each needs profile_url, profile_id, or full_name with current_employer; an entry matching an existing one (same profile, or same name and employer) is updated.
{ "entries": [{ "profile_id": "ACwAAA1", "status": "shortlisted", "tags": ["backend-ghent"], "external_ids": { "ats": "cand_123" } }] }
external_ids keeps your ATS ids next to each person, and is merged on update. tags replace the stored tags.
POST /v1/seen:check matches up to 1000 identities, in input order, and says whether each is seen and on what (profile or name_employer). GET /v1/seen lists entries, filtered by status or tag. PATCH and DELETE /v1/seen/{seen_id} edit or remove one; a removed person can show up in guided runs again.
Suppressions are separate: a suppressed person is removed from every result whatever the seen register says, and lifting a suppression leaves the seen entry in place.
Lists
Lists are named collections of people you want to keep together: a shortlist for a role, a pool to enroll.
| Call | Does |
|---|---|
POST /v1/lists | Create with name, description, and optional items |
GET /v1/lists, GET, PATCH, DELETE /v1/lists/{list_id} | List, read, rename, delete |
GET, POST /v1/lists/{list_id}/items | Read or add people. An item can carry profile_id, profile_url, email, company_url, and full_name with company, plus a note. People already on the list are skipped |
DELETE /v1/lists/{list_id}/items/{item_id} | Remove one |
GET /v1/lists/{list_id}/export | CSV, one row per person |
A suppressed person cannot be added, and disappears from item_count, the items list, and the CSV once they are suppressed. Matching uses whatever the item has: profile URL or id, company URL, email, or the normalized name together with the company. A name with no company is kept as a label and is not matched, because it is not unique. The same fields work on POST /v1/suppressions.
Enroll a whole list in outreach with list_id on POST /v1/outreach/enrollments.
MCP: save_to_list, list_lists, get_list, set_candidate_status, check_candidates.
What it costs
Free. The point is that the next paid fetch does not repeat.
Reference: the Building blocks tag in the API reference.