docs get started
API layers
Raw filters, building blocks, and guided searches, and when to use which.
The sourcing API has three layers. They share one code path, so scopes, previews, idempotency, error codes, and suppression behave the same in each. The API reference groups operations by these tags.
| Layer | Use it when | REST | MCP |
|---|---|---|---|
| Raw | You build your own ranking, ATS sync, or UI | POST /v1/people/search, POST /v1/people:fetch, GET /v1/people/{id}, POST /v1/people:match, contacts | search_people_raw, match_person (advanced toolset), lookup_people, find_contact_details |
| Building blocks | You need ids for filters, or memory between calls | /v1/lookups/*, POST /v1/companies:resolve, /v1/seen, /v1/lists | resolve_location, resolve_area, resolve_companies, list_filter_values, check_candidates, set_candidate_status, save_to_list |
| Guided | You start from a job and want a shortlist | /v1/intents, /v1/search-plans, /v1/runs | start_search, get_search_results, refine_search, extend_search |
Raw
- Filters map one to one to the person index: current and past titles and companies, schools, locations, industries, functions, seniority, years of experience, years at the current company, company headcount, profile language, first and last name, recently changed jobs, and keywords. Most have an
exclude_twin. - A filter the index cannot apply is refused with
400 unsupported_filterand a hint. Nothing is silently dropped. Each response listsapplied_filters. - Profiles are normalized and complete: name, headline, summary, photo, profile URL, locations, every experience with dates, education, skills, languages, certifications, open-to-work, and
fetched_at. We do not pass through the provider's raw record, andraw: trueis refused rather than ignored. That keeps the contract stable and versioned, and keeps provider fields you have no lawful use for out of your systems. - No result dedup by default: people in your seen register come back with
already_seen: true. Sendexclude_seen: trueto drop them.
Building blocks
Lookups, the seen register, and lists are free. The seen register is shared by every layer: mark people from your own pipeline with POST /v1/seen, and the next guided run skips them. Lists hold shortlists you can export or enroll.
Guided
Send job text, intent blocks (must, nice, exclude), or both. The plan returns a plain-language summary, the tier ladder, applied_filters, ignored_fields (what the search cannot use and why), and an estimate. A run searches tier by tier, fetches profiles, removes duplicates and people already seen, and stops at the target or the budget.
Always on
Suppression (opt-outs, erasures, and your own suppressions) applies in every layer, including raw search and fetches. Suppressed people are removed, counted in omitted.suppressed, and never charged. It cannot be turned off.
The full rationale, including why there is no raw record, is in docs/API-LAYERS.md in the repository.