Qualified search (L2)
Search qualified talents by prompt
Start a qualified talent search from a natural-language prompt.
POST
Search qualified talents by prompt
First time? Set up Authentication
Learn how to authenticate your API requests with your API key.
prompt. Kalent turns the prompt into search filters, then evaluates matching profiles against your qualification criteria (the criteria you send plus any criteria taken from the prompt). The request returns a castingId immediately. Poll GET /v1/search/talents/qualified/{castingId} while nextAction is wait, or receive a webhook when the call stops.
This is the natural-language counterpart of POST /v1/search/talents/qualified. The success response, the status values, and the webhooks are the same. The credit model (target, calls and waves, reservation, edge cases) is on the qualified search overview.
If the prompt cannot be turned into any search filters, the request returns prompt_interpretation_failed. After combining your qualificationCriterias with criteria taken from the prompt, at least one qualification criterion is required.
Request body
string
required
Natural-language description of the talent you want Kalent to qualify.
Trimmed. Minimum 1 character, maximum 4000 characters.
string[]
default:"[]"
Optional criteria Kalent uses to qualify matching profiles. Maximum 10 items.
Each string is trimmed, must be at least 1 character, and at most 300
characters. Kalent also extracts criteria from the prompt. At least one
criterion is required after that merge.
string
Language of the qualification texts (
recap, criterion title and result).
en or fr. Omitted: the language of the user who owns the API key,
changeable at
app.kalent.ai/settings/profile;
English when that user has none. Resolved once at start and stored on the
search; every continue keeps it. The same prompt and criteria in another
language are a different search: new castingId, new analysis, new
credits. Quotes in references stay in the profile’s original language. The
prompt itself can be written in any language. Details on POST /v1/search/talents/qualified.object
Quota of this call. Optional; each field you omit falls back to its default.
object
Optional. Where and for which verdicts Kalent sends events for this search. Stored on the search and reused by later continues unless they send another
webhook. Payload and headers are documented on POST /v1/search/talents/qualified.object
Optional JSON object with string keys. Stored on the search and echoed on
webhook payloads. The JSON serialization must be at most 4096 bytes.
boolean
default:"false"
When
false, a request with the same prompt, qualification criteria, and
resolved scoringLanguage as an existing qualified search returns that search
(reused: true) instead of starting another. When true, Kalent always
starts a new search.Response
New searches return 202. A reused search that is notrunning returns 200.
The X-Api-Credits-Remaining header is your workspace balance right after the request, that is after Kalent reserved min(balance, target.maxCredits) for this call. Unused reserved credits come back when each wave ends. GET does not send this header.
boolean
Whether the request completed without errors.
object
Present when
success is true.object
Present when
success is false.Unsupported location
Example
Go further
Optional. To check what Kalent reads in your prompt before you qualify:- Extract search from prompt returns the
filtersandqualificationCriteriasderived from a prompt. You can review and edit them, then start withPOST /v1/search/talents/qualifiedinstead. It costs 1 API credit. - Estimate talent pool counts the profiles that match those filters, without spending credits. Keep the default
gatemode: it is the mode qualified search runs in.

