docs sourcing

Intents

Job text and must, nice, and exclude blocks as an editable search profile.

An intent is what you are looking for, in blocks. POST /v1/intents reads titles, place, years, and tools from job_description (English, Dutch, French, or German), then applies any blocks you send on top. Every block and field is optional; set what you know.

{
  "job_description": "Senior backend engineer in Ghent. Go and Kubernetes, 5+ years.",
  "intent": {
    "role": { "titles": ["Backend Engineer"], "adjacent_titles": ["Platform Engineer"], "exclude_titles": ["Intern"] },
    "location": { "city": "Ghent", "radius_km": 30, "countries": ["Belgium"] },
    "must": { "tools": ["Go", "Kubernetes"], "min_years": 5, "max_years": 12 },
    "nice": { "companies": ["Showpad", "Deliverect"] },
    "exclude": { "current_companies": ["Acme"], "freelance": true }
  }
}

The draft reads the text with rules, not a language model. Read it back and patch what looks wrong before you plan.

Blocks

Block	Fields	Effect
`role`	`titles`, `adjacent_titles`, `exclude_titles`	Exact titles are searched first, adjacent titles after. Excluded titles remove a person
`location`	`city`, `radius_km` (10–100), `countries`, `anchors`, `whole_country`	Local tiers search around the city and anchors, then the rest of the country. A country is required to plan
`must`	`tools`, `min_years`, `max_years`, `languages`	Tools are tried first as keywords on exact-title tiers. Years become experience ranges. Spoken languages are not searchable
`nice`	`tools`, `companies`, `schools`	Preferred companies are searched first. Nice tools do not change the search
`exclude`	`current_companies`, `past_companies`, `freelance`, `seen`, `contacted`	Removes people. `seen` and `contacted` default to true
`industries`	`names`, `scope` (`strict`, `preferred`, `none`)	Strict filters on industry; preferred searches it first
`mode`	`standard` or `company_first`	Company-first starts from `nice.companies` and allows a target of 20

Applied and ignored

Every intent comes back with two lists, so nothing is silently dropped:

applied_filters: each field you set and how it shapes the search: hard_filter, search_order, exclusion, or result_filter.
ignored_fields: each field the search cannot use, with the reason. For example must.languages (spoken languages are not on the person index) or nice.schools in a guided plan.

warnings lists what the draft could not fill, such as a missing country.

Edit

PATCH /v1/intents/{intent_id} takes the blocks to change. Inside a block, the fields you send replace the stored ones and the rest stay.

{ "location": { "radius_km": 50 }, "exclude": { "past_companies": ["Acme"] } }

GET /v1/intents lists them, newest first. DELETE removes one; plans and runs made from it keep working.

You do not have to create an intent first. POST /v1/search-plans and POST /v1/runs accept the same job_description and intent inline.

What it costs

Free.

Reference: createIntent, updateIntent, and the IntentInput schema in the API reference.

API reference