Talent search (L1)
Search talents by prompt
Find professional profiles from a natural-language description.
POST
Search talents by prompt
First time? Set up Authentication
Learn how to authenticate your API requests with your API key.
filters array yourself, you send a single prompt and the API converts it into structured filters automatically — the same behaviour as the Kalent MCP search_talents_by_prompt tool.
This endpoint is the natural-language counterpart of POST /v1/search/talents. The success response is identical to that endpoint.
Everything you mention is a requirement
Each kind of criterion found in your prompt (job title, location, skill, language, years of experience, …) is treated as a requirement, with one rule:- Across kinds of criteria — all of them are required. A profile must satisfy every kind of criterion you mentioned.
- Within one kind of criterion — at least one value is enough. When you give several values of the same kind, a profile only needs to match one of them, not all — unless the prompt explicitly says they are all mandatory (
"must master both Python and React"), in which case each one is required.
"Software engineers in Paris or Lyon who know Python and React" returns profiles that are software engineers and based in Paris or Lyon and have Python or React — a profile with only Python still qualifies. To require both skills, say so explicitly in the prompt, or use POST /v1/search/talents and set isRequired: true on each SKILL filter.
Within the matching set, results are ordered by best overall match.
This differs from POST /v1/search/talents when you pass mode: "rank", described in Search modes. That endpoint defaults to gate, the same engine as this prompt endpoint. If you need optional preferences that never eliminate a profile, exclusions, exact matches, or a location radius that you control precisely, build the filters array yourself and call the filter-based endpoint with mode: "rank".
Only ready profiles are returned: talents that are already up to date, or that were synchronously refreshed and passed refiltering. The search keeps fetching until nbToFetch ready profiles are found or an internal page/time budget is reached; when fewer profiles are delivered the response is still 200 and resultCompleteness says why. An asynchronous refresh is omitted from this response and can appear on a later call.
Request body
string
required
A natural-language description of the talent you are looking for — e.g.
"Senior React developer in Paris with 5+ years experience". The API
interprets the prompt and derives the structured filters (job title, location,
skill, years of experience, etc.) used to run the search. Every kind of
criterion found in the prompt is required; when several values of the same
kind are given, matching one of them is enough unless the prompt explicitly
makes them all mandatory. If the prompt cannot be turned into any usable
filter, the request returns prompt_interpretation_failed.Array of
searchTransactionId values from previous search responses. When
provided, talents that were returned in those previous searches are excluded
from the current results. Use this field for pagination: after each
search, collect the searchTransactionId from the response and include it
(along with any earlier ones) in your next request to receive fresh,
non-overlapping results. Maximum 300 IDs. See Pagination below.number
default:"10"
How many ready talent profiles to return, between
1 and 10. One credit is
charged per profile actually returned. When fewer than nbToFetch ready
profiles can be delivered, the response is still 200 and
resultCompleteness explains why.integer
default:"1"
Profiles last updated more than this many months ago are live-refreshed before
being returned. More recent profiles are returned as is. Integer between
1
and 6. A higher value makes the search faster, but returns profiles that
were updated less recently. The default of 1 month is unchanged when the
field is omitted. Values outside 1–6 or non-integers return a 400
validation_error.Response
Successful responses carry two headers:boolean
Whether the request completed without errors.
object
Present when
success is true.object
Error details, present when
success is false.Pagination
Pagination works exactly like the filter-based endpoint: it uses a transaction-based pagination model instead of traditional page numbers. Send the sameprompt again and accumulate previous searchTransactionId values in the relatedSearchTransactionIds array — each new request excludes all talents from every prior transaction so you never see the same talent twice. The array accepts at most 300 IDs. See the Pagination section of POST /v1/search/talents for the full mechanism.
Response examples
200 — Success
200 — Success
Request
Response
422 — Prompt interpretation failed
422 — Prompt interpretation failed
Returned when the prompt could not be turned into any usable filter. Rephrase your prompt with more concrete search criteria (a role, a location, a skill, etc.).
Request
Response
422 — Unsupported location
422 — Unsupported location
Returned when a location in the prompt cannot be resolved. Remove that location or rephrase it. Retrying the same value will not succeed, and no credits are consumed.
Request
Response
400 — Validation error
400 — Validation error
Returned when the request body does not match the expected schema — for example when
prompt is missing or empty.Request
Response
401 — Authentication error
401 — Authentication error
Returned when the API key is missing or invalid.
Request
Response (missing key)
Response (invalid key)
402 — Insufficient API credits
402 — Insufficient API credits
Returned when your account does not have enough API credits to run the search. Top up your credits and retry.
Response

