Skip to main content
POST
Search qualified talents by prompt

First time? Set up Authentication

Learn how to authenticate your API requests with your API key.
Start a qualified search from a plain-language 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 not running 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.

Example