Hiring pipeline

The hiring pipeline is the board at /hire/pipeline: one per role, a column per stage, a card per person. Everything on it is reachable from code with the same key as the searches, and none of it costs a credit.

The usual job is a scheduled search whose results land on a role: run a filtered search, then post the people it returned straight to the role. Nobody already on the role is moved or duplicated, so the same script can run every morning.

Open a role#

curl https://www.refolk.ai/api/v1/pipelines \
  -H "Authorization: Bearer $REFOLK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Senior Backend Engineer", "company": "Acme", "template": "engineering"}'

Templates: standard (Sourced, Contacted, Screen, Interview, Offer, Hired, Rejected); engineering (Sourced, Contacted, Recruiter screen, Technical, Onsite, Offer, Hired, Rejected); agency (Sourced, Contacted, Interested, Submitted to client, Client interview, Offer, Placed, Rejected); sales (Sourced, Contacted, Screen, Hiring manager, Role play, Final round, Offer, Hired, Rejected); simple (Sourced, Talking, Hired, Rejected). Stages can be renamed and reordered on the board afterwards. Every stage has a kind - open, hired or rejected - and that, not the name, is what to branch on in code.

GET /api/v1/pipelines lists every role with a count per stage, and GET /api/v1/pipelines/{roleId} returns one role's stages and every candidate on it.

Add people#

await fetch("https://www.refolk.ai/api/v1/pipelines/" + roleId + "/candidates", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REFOLK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ candidates: people, stage: "Sourced" }),
});

A name or a linkedinUrl is enough for each person, and the people the search endpoints return are accepted exactly as they come. Up to 200 a call. The response splits them into added and existing: a person is the same person when their LinkedIn profile, GitHub login or email matches someone already on the role.

Move, rate and note#

PATCH /api/v1/candidates/{id} with {"stage": "onsite", "note": "Strong system design"} moves somebody. stage takes a stage id or its name, and loose names work: "rejected" finds the role's rejected column whatever it is called. rating is 1 (strong no) to 4 (strong yes), 0 to clear.

POST /api/v1/candidates/{id}/notes with {"body": "..."} leaves a note. Every change made through the API is marked as such on the candidate's timeline, so the people working the board can tell a script from a colleague.

From an assistant#

The MCP server has the same operations as tools, named refolk_pipeline_*, and they take names rather than ids: "move Jane Doe to onsite on the backend role" is one call.