> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search qualified talents by prompt

> Start a qualified talent search from a natural-language prompt.

<Card title="First time? Set up Authentication" icon="key" href="/authentication">
  Learn how to authenticate your API requests with your API key.
</Card>

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}`](/api-reference/get-qualified-search) while `nextAction` is `wait`, or receive a webhook when the call stops.

This is the natural-language counterpart of [`POST /v1/search/talents/qualified`](/api-reference/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](/api-reference/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

<ParamField body="prompt" type="string" required>
  Natural-language description of the talent you want Kalent to qualify. Trimmed. Minimum 1 character, maximum 4000 characters.
</ParamField>

<ParamField body="qualificationCriterias" type="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.
</ParamField>

<ParamField body="scoringLanguage" type="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](https://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`](/api-reference/search-talents-qualified#scoring-language).
</ParamField>

<ParamField body="target" type="object">
  Quota of **this call**. Optional; each field you omit falls back to its default.

  <Expandable title="target fields">
    <ParamField body="target.greens" type="number" default="10">
      Number of green talents to find during this call. Integer from 1 to 50. Greens already found on earlier calls do not count. A later continue reuses this number as the quota of that new call, unless the continue sends another value.
    </ParamField>

    <ParamField body="target.maxCredits" type="number" default="60">
      Maximum credits this call may spend. Even integer from 2 to 300. Two credits per analysed talent, so 60 credits is at most 30 talents.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook" type="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`](/api-reference/search-talents-qualified#webhooks).

  <Expandable title="webhook fields">
    <ParamField body="webhook.url" type="string" required>
      HTTPS URL that receives the events. Must not be `localhost` or a private network address.
    </ParamField>

    <ParamField body="webhook.verdicts" type="string[]" default="[&#x22;green&#x22;, &#x22;amber&#x22;, &#x22;red&#x22;]">
      Verdicts for which a `talent_judged` event is sent. One to three of `green`, `amber`, `red`, without duplicates. Omitted: all three. Filtering events changes neither the analysis nor the credits charged, and the end-of-call event is always sent.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customParams" type="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.
</ParamField>

<ParamField body="forceNew" type="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.
</ParamField>

## 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.

<ResponseField name="success" type="boolean">
  Whether the request completed without errors.
</ResponseField>

<ResponseField name="data" type="object">
  Present when `success` is `true`.

  <Expandable title="data fields">
    <ResponseField name="castingId" type="string">
      Identifier of the qualified search. Use it with GET and continue.
    </ResponseField>

    <ResponseField name="status" type="string">
      One of `running`, `can_continue`, `pool_exhausted`, `failed_retryable`.
    </ResponseField>

    <ResponseField name="reused" type="boolean">
      `true` when an existing qualified search for the same request was returned.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Present when `success` is `false`.

  <Expandable title="error fields">
    <ResponseField name="code" type="string">
      One of: `validation_error`, `no_qualification_criterias`, `prompt_interpretation_failed`, `insufficient_api_credits`, `casting_start_in_progress`, `search_engine_timeout`, `internal_error`, plus the authentication codes documented in [Authentication](/authentication).
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error description.
    </ResponseField>

    <ResponseField name="debugTrackingCode" type="string">
      Include this when contacting support.
    </ResponseField>

    <ResponseField name="available" type="number">
      Present when `code` is `insufficient_api_credits`.
    </ResponseField>

    <ResponseField name="required" type="number">
      Present when `code` is `insufficient_api_credits`. At least 2 credits are required to start.
    </ResponseField>
  </Expandable>
</ResponseField>

| HTTP status | Code                           | When                                                                                                                                                                                         |
| ----------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | `validation_error`             | Invalid body (including an odd or out-of-range `target.maxCredits`, a `target.greens` outside 1–50, a `webhook` without a valid HTTPS `url`, or a `scoringLanguage` other than `en` or `fr`) |
| 400         | `no_qualification_criterias`   | No qualification criterion remains after combining your list with criteria from the prompt                                                                                                   |
| 402         | `insufficient_api_credits`     | Fewer than 2 credits available                                                                                                                                                               |
| 409         | `casting_start_in_progress`    | Another start for the same request is already in progress                                                                                                                                    |
| 422         | `prompt_interpretation_failed` | The prompt could not be interpreted into search filters                                                                                                                                      |
| 504         | `search_engine_timeout`        | The search timed out                                                                                                                                                                         |
| 500         | `internal_error`               | Unexpected error                                                                                                                                                                             |

## Example

```bash theme={null}
curl -X POST https://app.kalent.ai/api/v1/search/talents/qualified/by-prompt \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "Senior engineer in Paris",
    "qualificationCriterias": ["Led a team"],
    "scoringLanguage": "fr",
    "target": { "greens": 10, "maxCredits": 60 }
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "castingId": "3f9d2c1e-7b4a-4e8f-9c21-5d6a8b0e4f17",
    "status": "running",
    "reused": false
  }
}
```