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

> Find professional profiles matching a set of filters.

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

Search the Kalent talent database using a combination of filters. Each filter targets a specific attribute (job title, location, skill, etc.) and can be marked as required, excluded, or exact-match. Results are ranked by best overall match.

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

<ParamField body="filters" type="object[]" required>
  Array of filter objects. Each object must include a `filterType` discriminator, a `value`, and modifier flags.

  Every filter accepts the following common fields:

  <Expandable title="Common filter fields">
    <ParamField body="filterType" type="string" required>
      The filter discriminator. See [filter types](#filter-types) below.
    </ParamField>

    <ParamField body="value" type="string" required>
      The search value. Accepted values depend on the `filterType`.
    </ParamField>

    <ParamField body="isRequired" type="boolean" required>
      When `true`, only talents matching this filter appear in results. Default to `true` unless the criterion is explicitly optional.
    </ParamField>

    <ParamField body="isExcluded" type="boolean" required>
      When `true`, talents matching this filter are removed from results.
    </ParamField>

    <ParamField body="isExactMatch" type="boolean" required>
      When `true`, the value must match exactly with no fuzzy matching.
    </ParamField>

    <ParamField body="radius" type="number">
      Search radius in kilometers. Only applies to `LOCATION` filters.
    </ParamField>

    <ParamField body="history" type="string">
      Temporal scope for the filter. One of `PAST`, `CURRENT`, or `CURRENT_AND_PAST`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="relatedSearchTransactionIds" type="string[]">
  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](#pagination) below.
</ParamField>

## Filter types

<AccordionGroup>
  <Accordion title="JOB_TITLE">
    Search by job title or role.

    | Field        | Value                                                        |
    | ------------ | ------------------------------------------------------------ |
    | `filterType` | `JOB_TITLE`                                                  |
    | `value`      | Free text — e.g. `"Product Designer"`, `"Software Engineer"` |

    ```json theme={null}
    {
      "filterType": "JOB_TITLE",
      "value": "Product Designer",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false,
      "history": "CURRENT"
    }
    ```
  </Accordion>

  <Accordion title="LOCATION">
    Search by geographic location.

    | Field        | Value                                               |
    | ------------ | --------------------------------------------------- |
    | `filterType` | `LOCATION`                                          |
    | `value`      | City or country — e.g. `"Paris"`, `"United States"` |
    | `radius`     | Optional. Kilometers around the location.           |

    ```json theme={null}
    {
      "filterType": "LOCATION",
      "value": "San Francisco",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false,
      "radius": 50
    }
    ```
  </Accordion>

  <Accordion title="YEARS_OF_EXPERIENCE">
    Search by years of professional experience.

    | Field        | Value                                                                    |
    | ------------ | ------------------------------------------------------------------------ |
    | `filterType` | `YEARS_OF_EXPERIENCE`                                                    |
    | `value`      | One of: `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, `30-100` |

    ```json theme={null}
    {
      "filterType": "YEARS_OF_EXPERIENCE",
      "value": "5-10",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="SKILL">
    Search by technical or soft skill.

    | Field        | Value                                              |
    | ------------ | -------------------------------------------------- |
    | `filterType` | `SKILL`                                            |
    | `value`      | Free text — e.g. `"React"`, `"Project Management"` |

    ```json theme={null}
    {
      "filterType": "SKILL",
      "value": "React",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="KEYWORD">
    Free-text search across the entire profile.

    | Field        | Value                                    |
    | ------------ | ---------------------------------------- |
    | `filterType` | `KEYWORD`                                |
    | `value`      | Free text — e.g. `"Figma"`, `"B2B SaaS"` |

    ```json theme={null}
    {
      "filterType": "KEYWORD",
      "value": "B2B SaaS",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="LANGUAGE">
    Search by spoken language.

    | Field        | Value                                                                |
    | ------------ | -------------------------------------------------------------------- |
    | `filterType` | `LANGUAGE`                                                           |
    | `value`      | Lowercase language name — e.g. `"french"`, `"english"`, `"mandarin"` |

    Common values: `english`, `french`, `spanish`, `german`, `portuguese`, `mandarin`, `japanese`, `korean`, `arabic`, `hindi`, `italian`, `dutch`, `russian`, `turkish`, `polish`, `swedish`.

    ```json theme={null}
    {
      "filterType": "LANGUAGE",
      "value": "french",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="LANGUAGE_PROFICIENCY">
    Search by language proficiency level.

    | Field        | Value                                           |
    | ------------ | ----------------------------------------------- |
    | `filterType` | `LANGUAGE_PROFICIENCY`                          |
    | `value`      | Proficiency level or language+level combination |

    ```json theme={null}
    {
      "filterType": "LANGUAGE_PROFICIENCY",
      "value": "native",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="COMPANY_NAME">
    Search by current or past employer.

    | Field        | Value                                     |
    | ------------ | ----------------------------------------- |
    | `filterType` | `COMPANY_NAME`                            |
    | `value`      | Free text — e.g. `"Google"`, `"McKinsey"` |

    ```json theme={null}
    {
      "filterType": "COMPANY_NAME",
      "value": "Google",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false,
      "history": "CURRENT_AND_PAST"
    }
    ```
  </Accordion>

  <Accordion title="COMPANY_SIZE">
    Search by employer company size.

    | Field        | Value                                                                                         |
    | ------------ | --------------------------------------------------------------------------------------------- |
    | `filterType` | `COMPANY_SIZE`                                                                                |
    | `value`      | One of: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` |

    ```json theme={null}
    {
      "filterType": "COMPANY_SIZE",
      "value": "51-200",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="COMPANY_INDUSTRY">
    Search by employer industry sector.

    | Field        | Value                                                                                            |
    | ------------ | ------------------------------------------------------------------------------------------------ |
    | `filterType` | `COMPANY_INDUSTRY`                                                                               |
    | `value`      | Industry string — e.g. `"computer software"`, `"financial services"`, `"hospital & health care"` |

    See the full list of accepted industries in the [industry values reference](#industry-values).

    ```json theme={null}
    {
      "filterType": "COMPANY_INDUSTRY",
      "value": "computer software",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="EDUCATION_DEGREE">
    Search by highest education level.

    | Field        | Value                                        |
    | ------------ | -------------------------------------------- |
    | `filterType` | `EDUCATION_DEGREE`                           |
    | `value`      | One of: `bachelors`, `masters`, `doctorates` |

    ```json theme={null}
    {
      "filterType": "EDUCATION_DEGREE",
      "value": "masters",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="EDUCATION_SCHOOL_NAME">
    Search by school or university.

    | Field        | Value                                   |
    | ------------ | --------------------------------------- |
    | `filterType` | `EDUCATION_SCHOOL_NAME`                 |
    | `value`      | Free text — e.g. `"MIT"`, `"HEC Paris"` |

    ```json theme={null}
    {
      "filterType": "EDUCATION_SCHOOL_NAME",
      "value": "HEC Paris",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="CERTIFICATION_NAME">
    Search by professional certification.

    | Field        | Value                                       |
    | ------------ | ------------------------------------------- |
    | `filterType` | `CERTIFICATION_NAME`                        |
    | `value`      | Free text — e.g. `"AWS Certified"`, `"PMP"` |

    ```json theme={null}
    {
      "filterType": "CERTIFICATION_NAME",
      "value": "AWS Certified",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="SENIORITY">
    Search by contract type.

    | Field        | Value                      |
    | ------------ | -------------------------- |
    | `filterType` | `SENIORITY`                |
    | `value`      | Currently only `Freelance` |

    ```json theme={null}
    {
      "filterType": "SENIORITY",
      "value": "Freelance",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="DURATION_IN_JOB">
    Search by tenure in current or last role.

    | Field        | Value                                                                    |
    | ------------ | ------------------------------------------------------------------------ |
    | `filterType` | `DURATION_IN_JOB`                                                        |
    | `value`      | One of: `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, `30-100` |

    ```json theme={null}
    {
      "filterType": "DURATION_IN_JOB",
      "value": "1-3",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="GRADUATION_YEAR">
    Search by graduation year.

    | Field        | Value                           |
    | ------------ | ------------------------------- |
    | `filterType` | `GRADUATION_YEAR`               |
    | `value`      | Four-digit year — e.g. `"2020"` |

    ```json theme={null}
    {
      "filterType": "GRADUATION_YEAR",
      "value": "2020",
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>

  <Accordion title="LINKEDIN_RELATIONS_DEGREE">
    Search by relationship to your connected LinkedIn account.

    | Field          | Value                           |
    | -------------- | ------------------------------- |
    | `filterType`   | `LINKEDIN_RELATIONS_DEGREE`     |
    | `value`        | One of: `1st degree`, `invited` |
    | `isExactMatch` | Always treated as `false`       |

    `1st degree` means accepted first-degree LinkedIn connections only. `invited` means pending LinkedIn invitations only. These values are distinct: `1st degree` does **not** include pending invitations.

    The API resolves the LinkedIn account from your authenticated Kalent user. If no LinkedIn account is connected, the request returns `missing_connected_linkedin_account`.

    ```json theme={null}
    {
      "filterType": "LINKEDIN_RELATIONS_DEGREE",
      "value": "1st degree",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Response

<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="talents" type="object[]">
      Array of matching talent profiles, ordered by relevance. Up to 10 results per request.

      <Expandable title="Talent object">
        <ResponseField name="id" type="string">
          Unique talent identifier.
        </ResponseField>

        <ResponseField name="firstname" type="string">
          First name.
        </ResponseField>

        <ResponseField name="lastname" type="string">
          Last name.
        </ResponseField>

        <ResponseField name="gender" type="string">
          Gender.
        </ResponseField>

        <ResponseField name="city" type="string">
          City of residence.
        </ResponseField>

        <ResponseField name="country" type="string">
          Country of residence.
        </ResponseField>

        <ResponseField name="jobTitle" type="string">
          Current job title.
        </ResponseField>

        <ResponseField name="summary" type="string">
          Professional summary.
        </ResponseField>

        <ResponseField name="state" type="string">
          State or region.
        </ResponseField>

        <ResponseField name="headline" type="string">
          LinkedIn headline.
        </ResponseField>

        <ResponseField name="photoUrl" type="string">
          URL to profile photo.
        </ResponseField>

        <ResponseField name="linkedinUrl" type="string">
          LinkedIn profile URL.
        </ResponseField>

        <ResponseField name="currentOrganization" type="object">
          Current employer.

          <Expandable title="properties">
            <ResponseField name="id" type="string">Organization ID.</ResponseField>
            <ResponseField name="name" type="string">Company name.</ResponseField>
            <ResponseField name="logoUrl" type="string">Company logo URL.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="experiences" type="object[]">
          Work experience entries.

          <Expandable title="properties">
            <ResponseField name="organizationName" type="string">Company name.</ResponseField>
            <ResponseField name="title" type="string">Job title.</ResponseField>
            <ResponseField name="startDate" type="string">Start date (ISO).</ResponseField>
            <ResponseField name="endDate" type="string">End date (ISO), `null` if current.</ResponseField>
            <ResponseField name="description" type="string">Role description.</ResponseField>
            <ResponseField name="isCurrent" type="boolean">Whether this is the current role.</ResponseField>

            <ResponseField name="organization" type="object">
              <Expandable title="properties">
                <ResponseField name="logoUrl" type="string">Company logo URL.</ResponseField>
                <ResponseField name="name" type="string">Company name.</ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="educations" type="object[]">
          Education entries.

          <Expandable title="properties">
            <ResponseField name="schoolName" type="string">Institution name.</ResponseField>
            <ResponseField name="schoolLogo" type="string">School logo URL.</ResponseField>
            <ResponseField name="summary" type="string">Education summary.</ResponseField>
            <ResponseField name="degrees" type="string[]">Degrees obtained.</ResponseField>
            <ResponseField name="majors" type="string[]">Major fields of study.</ResponseField>
            <ResponseField name="minors" type="string[]">Minor fields of study.</ResponseField>
            <ResponseField name="startDate" type="string">Start date.</ResponseField>
            <ResponseField name="endDate" type="string">End date.</ResponseField>
            <ResponseField name="schoolDomain" type="string">School website domain.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="skills" type="string[]">
          List of skills.
        </ResponseField>

        <ResponseField name="interests" type="string[]">
          List of interests.
        </ResponseField>

        <ResponseField name="languages" type="object[]">
          Spoken languages.

          <Expandable title="properties">
            <ResponseField name="name" type="string">Language name.</ResponseField>
            <ResponseField name="proficiency" type="string">Proficiency level.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="certifications" type="object[]">
          Professional certifications.

          <Expandable title="properties">
            <ResponseField name="name" type="string">Certification name.</ResponseField>
            <ResponseField name="organizationName" type="string">Issuing organization.</ResponseField>
            <ResponseField name="startDate" type="string">Issue date.</ResponseField>
            <ResponseField name="endDate" type="string">Expiry date.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="estimationCount" type="number">
      Estimated total number of talents matching the query across the entire database.
    </ResponseField>

    <ResponseField name="searchTransactionId" type="string">
      Unique identifier for this search transaction. Pass this value in `relatedSearchTransactionIds` on subsequent requests to paginate through results. Also useful for support requests and debugging.
    </ResponseField>

    <ResponseField name="pendingRefreshCount" type="number">
      Number of matching profiles in the current fetched batch that are currently being updated asynchronously and were therefore excluded from `talents`. This count is batch-scoped (not the full estimated result universe). When greater than zero, retry the same search shortly to retrieve those profiles once they are ready.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Error details, present when `success` is `false`.

  <Expandable title="error fields">
    <ResponseField name="code" type="string">
      Machine-readable error code. One of: `validation_error`, `too_many_search_transactions`, `insufficient_api_credits`, `search_engine_timeout`, `missing_connected_linkedin_account`, `missing_api_key`, `invalid_api_key`, `rate_limit_exceeded`, `internal_error`.
    </ResponseField>

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

    <ResponseField name="debugTrackingCode" type="string">
      Unique tracking code for this request. Include it when contacting support.
    </ResponseField>

    <ResponseField name="issues" type="object[]">
      Zod validation details. Only present when `code` is `validation_error`.
    </ResponseField>

    <ResponseField name="details" type="object">
      Rate limit details. Only present when `code` is `rate_limit_exceeded`.

      <Expandable title="details fields">
        <ResponseField name="window" type="string">
          The time window that was exceeded. One of: `minute`, `hour`, `day`, `month`.
        </ResponseField>

        <ResponseField name="limit" type="number">
          Maximum number of requests allowed in this window.
        </ResponseField>

        <ResponseField name="current" type="number">
          Number of requests already made in this window.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Pagination

The search API uses a **transaction-based pagination** model instead of traditional page numbers.

### How it works

1. **First request** — call the endpoint with your filters. The response includes a `searchTransactionId` and up to 10 matching talents.
2. **Next page** — send the **same filters** again, but add the previous `searchTransactionId` to the `relatedSearchTransactionIds` array. The API will exclude all talents that were already returned and give you the next batch.
3. **Subsequent pages** — keep accumulating `searchTransactionId` values in the array. Each new request excludes all talents from every prior transaction.

```bash theme={null}
# Page 1
curl -X POST https://app.kalent.ai/api/v1/search/talents \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "filters": [
      { "filterType": "JOB_TITLE", "value": "Software Engineer", "isRequired": true, "isExcluded": false, "isExactMatch": false }
    ]
  }'
# → response includes "searchTransactionId": "tx_aaa111"

# Page 2
curl -X POST https://app.kalent.ai/api/v1/search/talents \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "filters": [
      { "filterType": "JOB_TITLE", "value": "Software Engineer", "isRequired": true, "isExcluded": false, "isExactMatch": false }
    ],
    "relatedSearchTransactionIds": ["tx_aaa111"]
  }'
# → response includes "searchTransactionId": "tx_bbb222"

# Page 3
curl -X POST https://app.kalent.ai/api/v1/search/talents \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "filters": [
      { "filterType": "JOB_TITLE", "value": "Software Engineer", "isRequired": true, "isExcluded": false, "isExactMatch": false }
    ],
    "relatedSearchTransactionIds": ["tx_aaa111", "tx_bbb222"]
  }'
```

<Warning>
  **Non-deterministic results** — Search results are not guaranteed to be identical across requests, even with the same filters. This is by design:

  * **Real-time profile refresh**: talent profiles are enriched and updated in real time during search. A profile that did not match a filter moments ago may match now (and vice versa) after a refresh.
  * **AI-powered scoring**: result ranking uses AI models whose outputs can vary slightly between calls.
  * **Database updates**: new talents are continuously indexed and existing profiles are updated from external sources.

  The `relatedSearchTransactionIds` mechanism guarantees that you will **not see the same talent twice** across paginated requests, but the total pool of matching talents may shift between calls. This is inherent to a live, AI-augmented search engine and does not affect result accuracy — every returned talent genuinely matches your filters at the time of the request.

  Read more in the [Non-deterministic Results](/non-deterministic-results) guide.
</Warning>

## Response examples

<AccordionGroup>
  <Accordion title="200 — Success">
    ```bash Request theme={null}
    curl -X POST https://app.kalent.ai/api/v1/search/talents \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "filters": [
          {
            "filterType": "JOB_TITLE",
            "value": "Software Engineer",
            "isRequired": true,
            "isExcluded": false,
            "isExactMatch": false
          },
          {
            "filterType": "LOCATION",
            "value": "Paris",
            "isRequired": true,
            "isExcluded": false,
            "isExactMatch": false,
            "radius": 30
          }
        ]
      }'
    ```

    ```json Response theme={null}
    {
      "success": true,
      "data": {
        "talents": [
          {
            "id": "clx1abc2d3e4f5g6h7i8j9k0",
            "firstname": "Marie",
            "lastname": "Dupont",
            "gender": "female",
            "city": "Paris",
            "country": "France",
            "jobTitle": "Senior Software Engineer",
            "summary": "Full-stack engineer with 8 years of experience...",
            "state": "Île-de-France",
            "headline": "Senior Software Engineer at Acme Corp",
            "photoUrl": "https://media.licdn.com/dms/image/...",
            "linkedinUrl": "https://www.linkedin.com/in/marie-dupont",
            "currentOrganization": {
              "id": "org_abc123",
              "name": "Acme Corp",
              "logoUrl": "https://media.licdn.com/dms/image/..."
            },
            "experiences": [
              {
                "organizationName": "Acme Corp",
                "title": "Senior Software Engineer",
                "startDate": "2021-03-01T00:00:00.000Z",
                "endDate": null,
                "description": "Leading the frontend team...",
                "isCurrent": true,
                "organization": {
                  "logoUrl": "https://media.licdn.com/dms/image/...",
                  "name": "Acme Corp"
                }
              }
            ],
            "educations": [
              {
                "schoolName": "École Polytechnique",
                "schoolLogo": "https://media.licdn.com/dms/image/...",
                "summary": null,
                "degrees": ["Master of Science"],
                "majors": ["Computer Science"],
                "minors": [],
                "startDate": "2013-09-01T00:00:00.000Z",
                "endDate": "2017-06-30T00:00:00.000Z",
                "schoolDomain": "polytechnique.edu"
              }
            ],
            "skills": ["TypeScript", "React", "Node.js", "PostgreSQL"],
            "interests": ["Open Source", "Machine Learning"],
            "languages": [
              { "name": "French", "proficiency": "native_or_bilingual" },
              { "name": "English", "proficiency": "full_professional" }
            ],
            "certifications": [
              {
                "name": "AWS Solutions Architect",
                "organizationName": "Amazon Web Services",
                "startDate": "2023-01-15T00:00:00.000Z",
                "endDate": "2026-01-15T00:00:00.000Z"
              }
            ]
          }
        ],
        "estimationCount": 2430,
        "searchTransactionId": "st_xyz789",
        "pendingRefreshCount": 0
      }
    }
    ```
  </Accordion>

  <Accordion title="400 — Validation error">
    Returned when the request body does not match the expected schema.

    ```bash Request theme={null}
    curl -X POST https://app.kalent.ai/api/v1/search/talents \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "filters": [
          {
            "filterType": "INVALID_TYPE",
            "value": "test",
            "isRequired": true,
            "isExcluded": false,
            "isExactMatch": false
          }
        ]
      }'
    ```

    ```json Response theme={null}
    {
      "success": false,
      "error": {
        "code": "validation_error",
        "message": "Validation failed",
        "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
        "issues": [
          {
            "code": "invalid_union_discriminator",
            "options": ["JOB_TITLE", "LOCATION", "YEARS_OF_EXPERIENCE"],
            "path": ["filters", 0, "filterType"],
            "message": "Invalid discriminator value"
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="400 — Too many search transactions">
    Returned when `relatedSearchTransactionIds` contains more than 100 entries. Refine your search filters instead of paginating further.

    ```bash Request theme={null}
    curl -X POST https://app.kalent.ai/api/v1/search/talents \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "filters": [
          {
            "filterType": "JOB_TITLE",
            "value": "Software Engineer",
            "isRequired": true,
            "isExcluded": false,
            "isExactMatch": false
          }
        ],
        "relatedSearchTransactionIds": ["tx_1", "tx_2", "...", "tx_101"]
      }'
    ```

    ```json Response theme={null}
    {
      "success": false,
      "error": {
        "code": "too_many_search_transactions",
        "message": "Too many relatedSearchTransactionIds provided (max 100). Please refine your search filters to get more relevant results instead of paginating further.",
        "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
      }
    }
    ```
  </Accordion>

  <Accordion title="401 — Authentication error">
    Returned when the API key is missing or invalid.

    ```bash Request theme={null}
    curl -X POST https://app.kalent.ai/api/v1/search/talents \
      -H "Content-Type: application/json" \
      -d '{
        "filters": [
          {
            "filterType": "JOB_TITLE",
            "value": "Software Engineer",
            "isRequired": true,
            "isExcluded": false,
            "isExactMatch": false
          }
        ]
      }'
    ```

    ```json Response (missing key) theme={null}
    {
      "success": false,
      "error": {
        "code": "missing_api_key",
        "message": "Missing API key",
        "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
      }
    }
    ```

    ```json Response (invalid key) theme={null}
    {
      "success": false,
      "error": {
        "code": "invalid_api_key",
        "message": "Invalid API key",
        "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
      }
    }
    ```
  </Accordion>

  <Accordion title="429 — Rate limit exceeded">
    Returned when you exceed the rate limit for your API key. The `details` object tells you which time window was hit, the maximum allowed, and how many requests you have already made.

    ```json Response theme={null}
    {
      "success": false,
      "error": {
        "code": "rate_limit_exceeded",
        "message": "Rate limit exceeded: too many requests per minute",
        "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
        "details": {
          "window": "minute",
          "limit": 10,
          "current": 10
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="504 — Search engine timeout">
    Returned when the search engine request times out. Retry the same request; include the `debugTrackingCode` when contacting support.

    ```json Response theme={null}
    {
      "success": false,
      "error": {
        "code": "search_engine_timeout",
        "message": "The search request timed out. Please try again.",
        "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
      }
    }
    ```
  </Accordion>

  <Accordion title="500 — Server error">
    Returned when an unexpected error occurs. Include the `debugTrackingCode` when contacting support.

    ```json Response theme={null}
    {
      "success": false,
      "error": {
        "code": "internal_error",
        "message": "An error occurred during search talents",
        "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Industry values

<Accordion title="Full list of accepted industry values (147)">
  `information technology and services`, `government administration`, `retail`, `banking`, `construction`, `computer software`, `management consulting`, `real estate`, `hospital & health care`, `insurance`, `automotive`, `financial services`, `higher education`, `transportation/trucking/railroad`, `civic & social organization`, `environmental services`, `food production`, `aviation & aerospace`, `wholesale`, `mechanical or industrial engineering`, `telecommunications`, `research`, `pharmaceuticals`, `professional training & coaching`, `marketing and advertising`, `logistics and supply chain`, `hospitality`, `non-profit organization management`, `consumer goods`, `internet`, `renewables & environment`, `individual & family services`, `accounting`, `restaurants`, `defense & space`, `luxury goods & jewelry`, `machinery`, `chemicals`, `electrical/electronic manufacturing`, `human resources`, `sports`, `building materials`, `cosmetics`, `medical devices`, `oil & energy`, `staffing and recruiting`, `apparel & fashion`, `leisure, travel & tourism`, `architecture & planning`, `utilities`, `education management`, `health, wellness and fitness`, `farming`, `airlines/aviation`, `public policy`, `law practice`, `biotechnology`, `security and investigations`, `events services`, `food & beverages`, `industrial automation`, `broadcast media`, `facilities services`, `consumer services`, `medical practice`, `civil engineering`, `entertainment`, `wine and spirits`, `legal services`, `primary/secondary education`, `business supplies and equipment`, `media production`, `supermarkets`, `textiles`, `furniture`, `design`, `performing arts`, `publishing`, `sporting goods`, `semiconductors`, `newspapers`, `mining & metals`, `public relations and communications`, `packaging and containers`, `computer & network security`, `information services`, `international trade and development`, `music`, `e-learning`, `museums and institutions`, `computer games`, `plastics`, `printing`, `fine art`, `consumer electronics`, `mental health care`, `government relations`, `paper & forest products`, `public safety`, `online media`, `investment management`, `international affairs`, `recreational facilities and services`, `motion pictures and film`, `outsourcing/offshoring`, `maritime`, `military`, `graphic design`, `package/freight delivery`, `glass, ceramics & concrete`, `arts and crafts`, `market research`, `computer hardware`, `commercial real estate`, `venture capital & private equity`, `photography`, `shipbuilding`, `investment banking`, `railroad manufacture`, `gambling & casinos`, `veterinary`, `import and export`, `philanthropy`, `think tanks`, `translation and localization`, `animation`, `computer networking`, `political organization`, `warehousing`, `law enforcement`, `dairy`, `writing and editing`, `religious institutions`, `judiciary`, `ranching`, `libraries`, `nanotechnology`, `wireless`, `legislative office`, `program development`, `fishery`, `executive office`, `capital markets`, `alternative medicine`, `fund-raising`, `tobacco`, `alternative dispute resolution`
</Accordion>