Search
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 engine that powers the Kalent MCP search_talents tool. Results are ranked by best overall match.
This endpoint is the natural-language counterpart of POST /v1/search/talents. The success response is identical to that endpoint.
Only ready profiles are returned: talents that are already up to date, or that were synchronously refreshed and passed refiltering. Profiles currently being updated asynchronously are excluded from the current response and counted in pendingRefreshCount.
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. 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. See Pagination below.Response
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. 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
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
Search talents by prompt

