docs sourcing
Sourcing overview
Guided runs from job text, raw search, and the factual candidate fields.
Sourcing finds people with public professional profiles. You can drive it at three levels, and they share one memory: the seen register, lists, suppressions, and caches. API layers explains when to use which.
| Layer | You send | You get | Pages |
|---|---|---|---|
| Guided | Job text, or intent blocks | A planned, deduplicated shortlist of 30–60 full profiles | Intents, Search plans, Runs |
| Raw | Filters you choose | One page of the person index, and full profiles on request | Raw search, People and contacts |
| Building blocks | Places, companies, people | Ids for filters, and your own records | Lookups, Seen register and lists |
The guided path in one call
curl -s -X POST "$RECRUITMCP_BASE/v1/runs?dry_run=true" \
-H "Authorization: Bearer $RECRUITMCP_KEY" \
-H "Content-Type: application/json" \
-d '{"job_description": "Senior backend engineer in Ghent, Belgium. Go and Kubernetes, 5+ years."}'
The dry run is free. It returns the plan (tiers, a plain-language summary, applied_filters, ignored_fields, warnings) and the estimate. Send the same body without dry_run, with an Idempotency-Key header and a budget, to start the run. Over MCP the same flow is start_search, then start_search with confirm=true, then get_search_results.
- The text becomes an intent: titles, place, years, tools, in must, nice, and exclude blocks.
- The intent becomes a search plan: tiers that never pay twice for the same person.
- The run searches tier by tier, fetches full profiles, drops duplicates, suppressed people, and people already seen, and stops at the target or the budget.
Delivered candidates join the seen register unless mark_seen is false, so the next run skips them before paying for a profile.
Candidate facts
| Field | Meaning |
|---|---|
distance_km | Kilometres from the search anchor. Null when the profile has no usable location |
experience_years | Total experience derived from the profile |
tenure_months | Months in the current role |
tier | Which step of the plan found them: id, label, rank |
query_key | Which query found them |
identity_key | Stable person key used for deduplication |
The full profile is under profile: headline, summary, experience, education, skills, languages, certifications, and open_to_work.
Ask Claude
Here is the job description. Start a search, show me the summary and the maximum cost, and wait for my yes before you confirm.
What it costs
Lookups, intents, plans, and dry runs are free. Each lead returned is 1 credit, and a lead is charged once per workspace. A page holds up to 25 people; an empty page is free. Each live profile is 2 credits. See Credits.