Skip to main content
POST
Search qualified talents

First time? Set up Authentication

Learn how to authenticate your API requests with your API key.
Start a qualified search: Kalent finds matching profiles and evaluates each one against your qualificationCriterias. New to qualified search? Read the overview first. 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 filter-based counterpart of POST /v1/search/talents/qualified/by-prompt. Filters use the same model as POST /v1/search/talents.

How a call runs

Each start (and each continue) is a call with its own quota, target: target.greens greens to find during this call and a credit cap, target.maxCredits. Kalent chains analysis waves on its own until the call stops: green quota reached, cap spent, no more matching talents, or a failed wave. Two credits are charged per judged talent, at the end of each wave; Kalent never judges more talents in parallel than greens the call still needs, so a call never pays for a judgement started after its green quota was met. The full model — calls, waves, credits, reservation, edge cases — is on the qualified search overview.

Request body

object[]
required
Array of filter objects. Same shape as POST /v1/search/talents: each object needs filterType, value, isRequired, isExcluded, and isExactMatch. See filter types and accepted filter values.
string[]
required
Criteria Kalent uses to qualify matching profiles. At least one item is required. Maximum 10 items. Each string is trimmed, must be at least 1 character, and at most 300 characters.
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 filters 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. See Scoring language.
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. See Webhooks.
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 filters, 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.

Scoring language

Kalent writes recap, criterion title, and criterion result in one language for the whole search. By default this is the language of the user who owns the API key (set at app.kalent.ai/settings/profile; English when unset). Send scoringLanguage to override it for this search only. Quotes in references are copied verbatim from the profile and are never translated. The language is resolved when the search starts and is returned as scoringLanguage on GET. It cannot change afterwards: sending scoringLanguage on continue returns validation_error. Starting the same request in another language starts another search, with its own analysis and its own credits; change the profile language and the default follows for the next start, without touching running searches.

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, so the balance goes back up. 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.

Status values and nextAction

GET and the end-of-call webhook return both a status and a nextAction; follow nextAction. running / wait, can_continue / continue, failed_retryable / retry, pool_exhausted / done. See the overview.

Webhooks

When the search has a webhook.url, Kalent POSTs JSON to that URL for each judged talent whose verdict is in webhook.verdicts (talent_judged) and once when a call stops (wave_finished or pool_exhausted). Delivery rules, retries, headers, and how to authenticate the calls are on the overview. Headers: talent_judged body:
data.talent is the same object as one item in the GET talents array. Each criterion in data.talent.scoring.criterias carries title, result, status, evaluable, and references; recap, title, and result are written in the search’s scoring language. wave_finished and pool_exhausted body (end of a call):
eventType is pool_exhausted when the talent pool is exhausted, otherwise wave_finished (including when a wave failed, with data.status failed_retryable and data.nextAction retry). data.counts is { green, amber, red } for the whole search, regardless of webhook.verdicts. data.creditsCharged is the total charged on the search so far; creditsRemaining is only on GET. customParams is the object stored on the search, or null. sentAt is an ISO 8601 timestamp. eventType, castingId, customParams, and sentAt are the same on every event.

Example