# Hiring pipeline

> Roles, stages and candidates over HTTP. Open a role, drop a search's people onto it, move them through stages and leave notes. Free.

Canonical page: https://www.refolk.ai/developers/pipeline



The hiring pipeline is the board at [/hire/pipeline](/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](/developers/structured-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

```bash
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

```ts
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](/developers/mcp) 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.



---

## More of the API documentation

- [Quickstart](https://www.refolk.ai/developers/quickstart.md): Create a key, run your first search, and read what comes back. A working request in under two minutes, in curl, TypeScript, and Python.
- [Authentication](https://www.refolk.ai/developers/authentication.md): How API keys work: creating one, sending it, rotating it, and what happens when one leaks. Keys are shown once and hashed at rest.
- [Credits and limits](https://www.refolk.ai/developers/credits-and-limits.md): What each call costs, what a failed run is charged, what the rate limits are, and how to check a balance before a long run.
- [Playground](https://www.refolk.ai/developers/playground.md): Run any endpoint from the browser, signed in, on your own credits. Prefilled examples, the real response, and the equivalent curl for your own code.
- [Search in plain English](https://www.refolk.ai/developers/agentic-search.md): POST /v1/search. One sentence in, a ranked shortlist out, with the evidence behind every pick. Blocking or streamed as server-sent events.
- [Search with filters](https://www.refolk.ai/developers/structured-search.md): POST /v1/people/search. An exact filter set in, a deterministic page of people out, one flat price a page. Every field, every allowed value, and how to paginate.
- [Errors](https://www.refolk.ai/developers/errors.md): One error shape for every endpoint, a closed set of types, and which of them are worth retrying. What gets refunded when a call fails.
- [MCP server](https://www.refolk.ai/developers/mcp.md): Give Claude, Cursor, VS Code, or any MCP client the ability to search for people mid-conversation. One URL, one header, and your hiring pipeline is reachable too.
- [Jobs API and MCP](https://www.refolk.ai/developers/jobs.md): Search open jobs for free with no key, then start and send applications on the person's account. A REST API and an MCP server that signs in only when it has to.
- [OpenAPI document](https://www.refolk.ai/api/v1/openapi.json): the machine-readable specification.

Authenticate with `Authorization: Bearer rfk_live_...`. Keys are created at https://www.refolk.ai/hire/api.