Recruiting CRM / ATS

Vincere

Everything you sourced lands in Vincere, on the right record.

Vincere is where the desk runs. Your agent searches what you already have before it creates anything, so you do not end up with duplicates, then writes the genuinely new ones in. It reads your jobs, companies and contacts as well.

Vincere is the destination. Sourcing and enrichment feed it.

things you can ask for

“Push this shortlist in, skipping anyone already on the database”
“What jobs am I working? Build a longlist for this one using Apollo”
“Update this record with the mobile LeadMagic found”
“Write the Fathom debrief onto the candidate”

works well with Vincere

Apollo
source against the roles already live in Vincere
LeadMagic
fill the contact gaps on records you already hold
Fathom
interview debriefs onto the candidate record
SourceWhale
outreach shaped the way the desk is measured

What your agent reads before it touches Vincere

Every tool ships with a written playbook, and the agent loads it before the first call. Auth, rate limits, what each call costs, which actions need your approval, and the mistakes worth avoiding. It is the difference between an agent that knows the tool and one that guesses at it.

Read the Vincere docs →

Show the raw playbookwritten for the agent

HOW in lib/vincere.py.

Auth & config (two headers)

Base URL: https://{VINCERE_TENANT}.vincere.io/api/v2.
Auth: BOTH x-api-key (company API key) AND id-token (OAuth id_token, ~30 min TTL).
Env: VINCERE_TENANT, VINCERE_API_KEY, VINCERE_ID_TOKEN. Never hardcode.
The id_token expires fast — mint/refresh it via the Vincere OAuth (Auth0) flow externally, then set_id_token(...) or re-set env. github.com/vincere-io/vincere-identity has the flow.

Operations (paths CONFIRMED 2026-06-01; full spec signup-gated)

Candidates: search_candidates, get_candidate, create_candidate, update_candidate. Reads: search_jobs, get_job, search_companies, search_contacts. Index: reference/docs/vincere/raw/endpoints.md.

Jobs are job (NOT position) in v2 — confirmed. Search paths carry a trailing slash (/candidate/search/).
Search quirk: fl/sort are matrix params on the path (/candidate/search/fl=id,name;sort=created_date asc?q=...), q is a query param. The client passes fl/q as query params; if a search 400s, build the matrix path via request().

Guardrail

Production ATS writes — pilot one, confirm, then bulk. Watch for id_token expiry (refresh + retry).

Handoff

ATS write target: enriched candidates → create_candidate.

Callable surface — `lib/vincere.py`

Import: from lib.vincere import Vincere → instantiate Vincere() (reads key from env). Generic passthrough: request(method, path, *, params, json).

create_candidate(payload: dict) -> Any — POST /candidate — create a candidate.
get_candidate(candidate_id: str, *, fields: str | None = None) -> Any
get_job(job_id: str, *, fields: str | None = None) -> Any
search_candidates(q: str, *, fl: str | None = None, **params) -> Any — GET /candidate/search/ — q query (Lucene-style), fl=fields (see matrix-param note in module doc).
search_companies(q: str, *, fl: str | None = None, **params) -> Any — GET /company/search/.
search_contacts(q: str, *, fl: str | None = None, **params) -> Any — GET /contact/search/.
search_jobs(q: str, *, fl: str | None = None, **params) -> Any — GET /job/search/ — jobs are job in Vincere v2 (CONFIRMED — not position).
set_id_token(id_token: str) — Swap in a freshly-refreshed id_token (they expire ~30 min).
update_candidate(candidate_id: str, payload: dict) -> Any