Sourcing · from your code · Product team
Build a recruiting product on the API
Use sourcing as a backend: an OpenAPI contract, dry-run estimates to show your users, and spend caps per key.
Who it is for
Developers adding sourcing to an ATS, a vertical recruiting tool, or an internal platform, who do not want to run their own data pipeline.
The problem
Building sourcing in-house means search providers, dedup, caching, budgets, and GDPR deletes before the first feature ships.
Workflow
- 01
Contract
Use the TypeScript or Python SDK, or generate a client from /openapi.yaml. Pin RecruitMCP-Version; every response echoes it.
- 02
Estimate
POST /v1/runs?dry_run=true returns the estimate and spends nothing. Show it to your user before they commit.
- 03
Customers
One customer per client of yours, each with its own seen register, lists, and daily cap, selected with the RecruitMCP-Customer header. All share one balance.
- 04
Privacy
Suppressions and erasures are endpoints, so an opt-out in your product reaches the same register.
Sample transcript
- Tool call: POST /v1/runs?dry_run=true { job_description: "…", target: 40 }
- Result: ← 200 · credits_min 1 · credits_max 120 · nothing spent
- You: Your user clicks Run.
- Tool call: POST /v1/runs Idempotency-Key: 7c1e… { plan_id: "pln_9", budget: { max_credits: 120 } }
- Result: ← 202 accepted · RecruitMCP-Version: 2026-11-01
- Tool call: POST /v1/suppressions { profile_id: "…" }
- Result: ← suppressed · not fetched or charged again
Outcome
- Sourcing behind your own UI, with an estimate your users see before anything is spent.
- Retries and double clicks never charge twice.
- Opt-outs and erasures handled over the API, not by email.
Prompts for your coding agent
Typed client
“Use the RecruitMCP TypeScript SDK to dry-run createRun from our job text, show credits_max, and start the run only after the user confirms.”
Estimate in the UI
“Add a "Find candidates" button to our job page: build the plan, show credits_max, and only start the run after the user confirms.”
Opt-outs
“When a candidate opts out in our product, send their profile URL to the RecruitMCP suppressions endpoint.”
Tools and endpoints
| tool | endpoint |
|---|---|
| start_search | POST /v1/runs |
| get_search_results | GET /v1/runs/{run_id}/candidates |
| check_candidates | POST /v1/seen:check |
| add_suppression | POST /v1/suppressions |
Credit cost
example data| Dry-run estimate | 0 |
|---|---|
| One run of 40 people | 120 |
| Seen checks and suppressions | 0 |
| Total | 120 |
Example data. API calls are billed exactly like the same steps from an agent.