Kalent API

https://docs.kalent.ai/
Admin
Kalent API is a talent search engine that enables programmatic access to professional profiles,...
Tokens:18,943
Snippets:96
Trust Score:7.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### API Request: Authentication Error Example (401)

Source: https://docs.kalent.ai/api-reference/search-talents

This section shows an example request for the search talents API and the corresponding JSON responses for missing or invalid API keys. Authentication errors (401) occur when the API key is not provided or is incorrect.

```bash
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
{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
```

```json
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
```

--------------------------------

### GET /talents

Source: https://docs.kalent.ai/api-reference/search-talents

Retrieves a list of matching talent profiles based on search criteria, ordered by relevance.

```APIDOC
## GET /talents

### Description
Retrieves an array of talent profiles matching the search criteria. Results are limited to 10 profiles per request.

### Method
GET

### Endpoint
/talents

### Parameters
#### Query Parameters
- **query** (string) - Required - The search string or criteria for filtering talents.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the talent results.
  - **talents** (array) - List of talent objects.
    - **id** (string) - Unique talent identifier.
    - **firstname** (string) - First name.
    - **lastname** (string) - Last name.
    - **jobTitle** (string) - Current job title.
    - **skills** (array) - List of skills.
    - **experiences** (array) - Work history entries.

#### Response Example
{
  "success": true,
  "data": {
    "talents": [
      {
        "id": "t123",
        "firstname": "Jane",
        "lastname": "Doe",
        "jobTitle": "Software Engineer",
        "skills": ["JavaScript", "React"]
      }
    ]
  }
}
```

--------------------------------

### API Too Many Search Transactions Error Response (Bash)

Source: https://docs.kalent.ai/api-reference/search-talents

Shows an example of an API request that would be rejected because the `relatedSearchTransactionIds` parameter exceeds the limit of 100 entries. This indicates that the search filters need to be refined.

```bash
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",

```

--------------------------------

### Authentication Overview

Source: https://docs.kalent.ai/authentication

Explains how to authenticate requests to the Kalent API using either the x-api-key header or Bearer token authentication.

```APIDOC
## Authentication

### Description
All requests to the Kalent API require a valid workspace API key. You can authenticate using either the `x-api-key` header or a `Bearer` token.

### Authentication Methods
- **x-api-key header**: Pass the key in the `x-api-key` header.
- **Bearer token**: Pass the key in the `Authorization` header as `Bearer YOUR_API_KEY`.

### Request Example (Header)
```bash
curl -X POST https://app.kalent.ai/api/v1/search/talents \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": []}'
```

### Error Handling
- **401 Unauthorized**: Returned when the API key is missing or invalid.
- **429 Too Many Requests**: Returned when rate limits are exceeded.
```

--------------------------------

### Authenticate API Requests with API Key

Source: https://docs.kalent.ai/authentication

Demonstrates how to authenticate API requests to Kalent.ai using either an 'x-api-key' header or an 'Authorization: Bearer' token. Both methods require your unique API key and specify the content type and request body.

```bash
curl -X POST https://app.kalent.ai/api/v1/search/talents \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": []}'
```

```bash
curl -X POST https://app.kalent.ai/api/v1/search/talents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": []}'
```

--------------------------------

### API Response: Too Many Search Transactions (400)

Source: https://docs.kalent.ai/api-reference/search-talents

This error is returned when the number of 'relatedSearchTransactionIds' exceeds the maximum limit (100). It suggests refining search filters to get more relevant results instead of paginating further.

```json
{
  "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"
  }
}
```

--------------------------------

### Search Talents via REST API

Source: https://docs.kalent.ai/

Demonstrates how to perform a talent search by sending a POST request to the Kalent API. It includes mandatory headers for authentication and a JSON payload defining job title and location filters.

```bash
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
      }
    ]
  }'
```

--------------------------------

### Successful Talent Search Request and Response (Bash/JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

Demonstrates a successful API request to search for talents using specific filters and the corresponding JSON response containing talent data. This includes details about the talent's experience, education, skills, and more.

```bash
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
{
  "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"
  }
}
```

--------------------------------

### Implement Transaction-Based Pagination with cURL

Source: https://docs.kalent.ai/api-reference/search-talents

This snippet demonstrates how to perform paginated searches using cURL. The first request retrieves an initial set of results and a transaction ID, which is then included in the second request to fetch the next page of results.

```bash
# 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"
```

--------------------------------

### POST /talents/search

Source: https://docs.kalent.ai/api-reference/search-talents

Search for professional profiles in the Kalent database based on specific criteria and filter configurations.

```APIDOC
## POST /talents/search

### Description
Search the Kalent talent database using a combination of filters. Results are ranked by best overall match.

### Method
POST

### Endpoint
/talents/search

### Parameters
#### Request Body
- **filters** (object[]) - Required - Array of filter objects defining search criteria.
- **relatedSearchTransactionIds** (string[]) - Optional - Array of transaction IDs used for pagination to exclude previously seen results.

### Request Example
{
  "filters": [
    {
      "filterType": "JOB_TITLE",
      "value": "Software Engineer",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false
    }
  ],
  "relatedSearchTransactionIds": []
}

### Response
#### Success Response (200)
- **talents** (array) - List of matching professional profiles.
- **searchTransactionId** (string) - Unique ID for this search session, used for pagination.

#### Response Example
{
  "talents": [],
  "searchTransactionId": "txn_12345"
}
```

--------------------------------

### POST /search_talents

Source: https://docs.kalent.ai/mcp/search-talents

Executes a search against the Kalent talent database based on natural language criteria.

```APIDOC
## POST /search_talents

### Description
Translates natural language prompts into structured filters to search for talent profiles in the Kalent database. Returns up to 5 matching profiles with detailed career information.

### Method
POST

### Endpoint
/search_talents

### Parameters
#### Request Body
- **prompt** (string) - Required - The natural language description of the talent you are looking for (e.g., "Senior React developers in Berlin with 5-10 years experience").

### Request Example
{
  "prompt": "Find me a Product Designer with experience in fintech and fluent in Spanish."
}

### Response
#### Success Response (200)
- **profiles** (array) - A list of up to 5 matching candidate profiles.

#### Response Example
{
  "profiles": [
    {
      "name": "Jane Doe",
      "title": "Product Designer",
      "experience": "5-10 years",
      "skills": ["Figma", "React", "Fintech"],
      "languages": ["Spanish", "English"]
    }
  ]
}
```

--------------------------------

### Add Claude MCP Client CLI

Source: https://docs.kalent.ai/mcp/overview

This command adds the Kalent MCP client to your Claude application via the command line interface. It specifies the transport protocol and the server URL.

```bash
claude mcp add --transport http kalent https://app.kalent.ai/api/mcp
```

--------------------------------

### Configuration Flags in JavaScript

Source: https://docs.kalent.ai/api-reference/search-talents

Demonstrates the usage of boolean configuration flags within a JavaScript object. These flags control aspects of data processing or validation, such as requirement status, exclusion criteria, and matching exactness.

```javascript
{
      "isRequired": false,
      "isExcluded": false,
      "isExactMatch": false
    }
```

--------------------------------

### Pagination

Source: https://docs.kalent.ai/mcp/search-talents

Explains how to use `relatedSearchTransactionIds` for paginating through search results and avoiding duplicates.

```APIDOC
## Pagination

When you ask for more results, the AI automatically handles pagination by passing previous `searchTransactionId` values via the `relatedSearchTransactionIds` parameter. `relatedSearchTransactionIds` is an array of `searchTransactionId` strings from previous `search_talents` calls — talents already returned in those earlier searches are excluded from the new results, so you always see fresh profiles.

> **You:** Find me React developers in Paris.
> 
> *[5 results displayed — estimationCount: 120]*
> 
> **You:** Show me more.
> 
> *[5 new, different results displayed — no duplicates from the first batch]*

The AI collects `searchTransactionId` values from each response and passes them in subsequent requests so you never see the same talent twice. The `estimationCount` tells you how many total matches exist, helping you decide whether to paginate further.
```

--------------------------------

### Filter by Company Size (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet demonstrates how to filter job searches by the size of the employer's company. The 'value' field accepts predefined ranges.

```json
{
  "filterType": "COMPANY_SIZE",
  "value": "51-200",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Search Talents API - Filter Types Overview

Source: https://docs.kalent.ai/api-reference/accepted-filter-values

Provides an overview of available filter types for the Search Talents endpoint, including their value formats and applicability for 'radius' and 'history' parameters.

```APIDOC
## Search Talents API - Filter Types Overview

This section details the available filter types for the Search Talents endpoint. Each filter requires a `filterType` discriminator, and this table outlines the supported types, their value formats, and whether they accept `radius` or `history` parameters.

### Filter Types Table

| Filter type             | Value format            | `radius` | `history` |
| ----------------------- | ----------------------- | :------: | :-------: |
| `JOB_TITLE`             | Free text               |     —    |     ✓     |
| `LOCATION`              | City or country         |     ✓    |     —     |
| `YEARS_OF_EXPERIENCE`   | Range bucket            |     —    |     —     |
| `SKILL`                 | Free text               |     —    |     —     |
| `KEYWORD`               | Free text               |     —    |     —     |
| `LANGUAGE`              | Lowercase language name |     —    |     —     |
| `LANGUAGE_PROFICIENCY`  | Proficiency level       |     —    |     —     |
| `COMPANY_NAME`          | Free text               |     —    |     ✓     |
| `COMPANY_SIZE`          | Range bucket            |     —    |     —     |
| `COMPANY_INDUSTRY`      | Industry string         |     —    |     —     |
| `EDUCATION_DEGREE`      | Degree level            |     —    |     —     |
| `EDUCATION_SCHOOL_NAME` | Free text               |     —    |     —     |
| `CERTIFICATION_NAME`    | Free text               |     —    |     —     |
| `SENIORITY`             | Contract type           |     —    |     —     |
| `DURATION_IN_JOB`       | Range bucket            |     —    |     —     |
| `GRADUATION_YEAR`       | Four-digit year         |     —    |     —     |
```

--------------------------------

### Search Filter Definitions

Source: https://docs.kalent.ai/api-reference/search-talents

Overview of the available filter types used to construct search queries in the Kalent AI system.

```APIDOC
## Filter Types Overview

### Description
This documentation outlines the structure for various filter types used to query candidate profiles. Each filter requires a `filterType` identifier and a corresponding `value`.

### Common Fields
- **filterType** (string) - Required - The type of filter (e.g., JOB_TITLE, LOCATION).
- **value** (string) - Required - The search criteria value.
- **isRequired** (boolean) - Optional - Whether the filter is mandatory.
- **isExcluded** (boolean) - Optional - Whether to exclude results matching this filter.
- **isExactMatch** (boolean) - Optional - Whether to perform an exact match search.

### Supported Filter Types
- **JOB_TITLE**: Search by job title or role.
- **LOCATION**: Search by geographic location (supports optional `radius` in km).
- **YEARS_OF_EXPERIENCE**: Search by experience brackets (e.g., '5-10').
- **SKILL**: Search by technical or soft skills.
- **KEYWORD**: Free-text search across profiles.
- **LANGUAGE**: Search by spoken language.
- **LANGUAGE_PROFICIENCY**: Search by proficiency level.
- **COMPANY_NAME**: Search by current or past employer.

### Request Example
{
  "filterType": "JOB_TITLE",
  "value": "Product Designer",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false,
  "history": "CURRENT"
}
```

--------------------------------

### Response Structure

Source: https://docs.kalent.ai/mcp/search-talents

Details the two main components of the API response: structured JSON and a Markdown summary table.

```APIDOC
## Response

Each search returns two content blocks:

### 1. Structured JSON

Complete profile data for each matching talent, including:

* `searchTransactionId` — unique identifier for this search (used for pagination)
* `estimationCount` — the total estimated number of talents matching the filters in the database, not just the ones returned in this batch
* Full name, location, headline
* Current job title and organization
* Work experiences (company, title, dates, description)
* Education (school, degree, major, dates)
* Skills
* Languages and proficiency levels
* Professional certifications
* LinkedIn profile URL

The AI uses this data to answer follow-up questions, compare candidates, or refine searches. The `searchTransactionId` is used internally for pagination (see below). The `estimationCount` helps convey how large the overall talent pool is for the given criteria.

### 2. Markdown Summary Table

A formatted table displayed directly in the conversation:

| # | Name         | Job Title                | Company   | Location      | LinkedIn                               |
| - | ------------ | ------------------------ | --------- | ------------- | -------------------------------------- |
| 1 | Marie Dupont | Senior Software Engineer | Acme Corp | Paris, France | [Profile](https://linkedin.com/in/...) |
| 2 | John Smith   | Staff Engineer           | Tech Inc  | London, UK    | [Profile](https://linkedin.com/in/...) |
```

--------------------------------

### Search Talents via REST API

Source: https://docs.kalent.ai/api-reference/search-talents

Executes a POST request to search for talent profiles based on job title filters. It requires an API key in the header and supports pagination tracking via relatedSearchTransactionIds.

```bash
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"]
  }'
```

--------------------------------

### Filter by Seniority (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet demonstrates filtering by seniority, currently limited to 'Freelance' as the only accepted value for the 'value' field.

```json
{
  "filterType": "SENIORITY",
  "value": "Freelance",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Authentication Error

Source: https://docs.kalent.ai/api-reference/search-talents

Handles errors related to API key authentication, including missing or invalid keys.

```APIDOC
## Authentication Errors

### Description
This section details the error responses related to API key authentication.

### Method
POST

### Endpoint
https://app.kalent.ai/api/v1/search/talents

### Error Handling
#### 401 — Authentication error
Returned when the API key is missing or invalid.

##### Request Example (Missing Key)
```bash
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
      }
    ]
  }'
```

##### Response Example (Missing Key)
```json
{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
```

##### Response Example (Invalid Key)
```json
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
```
```

--------------------------------

### API Response: Server Error (500)

Source: https://docs.kalent.ai/api-reference/search-talents

This response indicates an unexpected server-side error occurred during the API request. Users are advised to include the 'debugTrackingCode' when contacting support.

```json
{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An error occurred during search talents",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
```

--------------------------------

### Filter by Certification Name (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet shows how to filter job searches by professional certifications. The 'value' field accepts free text, such as 'AWS Certified' or 'PMP'.

```json
{
  "filterType": "CERTIFICATION_NAME",
  "value": "AWS Certified",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Define Keyword Filter

Source: https://docs.kalent.ai/api-reference/search-talents

Configures a free-text search filter that scans the entire candidate profile. This is useful for broad searches across various profile attributes.

```json
{
  "filterType": "KEYWORD",
  "value": "B2B SaaS",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Server Error

Source: https://docs.kalent.ai/api-reference/search-talents

Describes the error response for unexpected server-side issues.

```APIDOC
## Server Error

### Description
This section details the error response for unexpected server-side issues.

### Method
POST

### Endpoint
https://app.kalent.ai/api/v1/search/talents

### Error Handling
#### 500 — Server error
Returned when an unexpected error occurs. Include the `debugTrackingCode` when contacting support.

##### Response Example
```json
{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An error occurred during search talents",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
```
```

--------------------------------

### Filter by Duration in Job (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet illustrates filtering by tenure in a current or last role. The 'value' field accepts predefined ranges for duration.

```json
{
  "filterType": "DURATION_IN_JOB",
  "value": "1-3",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Non-deterministic Results

Source: https://docs.kalent.ai/mcp/search-talents

Addresses the non-deterministic nature of search results and explains why they may vary between identical requests.

```APIDOC
## Non-deterministic Results

Search results may vary between identical requests. This is expected and by design:

* **Real-time profile refresh** — talent profiles are enriched and updated live during each search. A profile that didn't match before may match now after a refresh (and vice versa).
* **AI-powered scoring** — result ranking uses AI models whose outputs can differ slightly between calls.
* **Continuous indexing** — new talents are added and existing profiles are updated from external sources on an ongoing basis.

The pagination mechanism guarantees you will **never see the same talent twice** within a paginated session. However, the overall set 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 criteria at the time of the request.
```

--------------------------------

### Filter by School Name (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet demonstrates how to filter job searches by the name of the school or university attended. The 'value' field accepts free text input.

```json
{
  "filterType": "EDUCATION_SCHOOL_NAME",
  "value": "HEC Paris",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Define Experience Filter

Source: https://docs.kalent.ai/api-reference/search-talents

Configures a filter to search for candidates based on years of professional experience. The value must be selected from a predefined set of experience ranges.

```json
{
  "filterType": "YEARS_OF_EXPERIENCE",
  "value": "5-10",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### POST /api/v1/search/talents

Source: https://docs.kalent.ai/api-reference/search-talents

Searches for talents based on provided filters and related search transaction IDs. Results may vary due to real-time data updates and AI scoring.

```APIDOC
## POST /api/v1/search/talents

### Description
Searches for talents based on provided filters and related search transaction IDs. This endpoint is designed to leverage real-time data enrichment and AI-powered scoring to provide relevant talent matches.

### Method
POST

### Endpoint
/api/v1/search/talents

### Parameters
#### Query Parameters
- **x-api-key** (string) - Required - Your API key for authentication.

#### Request Body
- **filters** (array) - Required - An array of filter objects to narrow down the talent search.
  - **filterType** (string) - Required - The type of filter (e.g., JOB_TITLE, SKILL, LOCATION).
  - **value** (string) - Required - The value for the filter.
  - **isRequired** (boolean) - Required - Whether this filter is mandatory.
  - **isExcluded** (boolean) - Required - Whether to exclude talents matching this filter.
  - **isExactMatch** (boolean) - Required - Whether the match must be exact.
- **relatedSearchTransactionIds** (array) - Optional - A list of transaction IDs to ensure no duplicate talents are returned across paginated requests.
  - (string) - A search transaction ID.

### Request Example
```json
{
  "filters": [
    { "filterType": "JOB_TITLE", "value": "Software Engineer", "isRequired": true, "isExcluded": false, "isExactMatch": false }
  ],
  "relatedSearchTransactionIds": ["tx_aaa111", "tx_bbb222"]
}
```

### Response
#### Success Response (200)
- **talents** (array) - A list of talent objects matching the search criteria.
  - Each talent object contains profile details, skills, experience, etc.
- **searchTransactionId** (string) - The unique ID for this search transaction, to be used in subsequent requests for pagination.

#### Response Example
```json
{
  "talents": [
    {
      "id": "talent_123",
      "name": "Jane Doe",
      "jobTitle": "Senior Software Engineer",
      "skills": ["Java", "Python", "Cloud Computing"],
      "experienceYears": 8
    }
    // ... more talents
  ],
  "searchTransactionId": "tx_ccc333"
}
```

### Warning
**Non-deterministic results** — Search results are not guaranteed to be identical across requests, even with the same filters. This is due to real-time profile refresh, AI-powered scoring variations, and continuous database updates. The `relatedSearchTransactionIds` mechanism helps prevent seeing the same talent twice across paginated requests, but the overall pool of matching talents may shift between calls.
```

--------------------------------

### Search Talents API

Source: https://docs.kalent.ai/api-reference/search-talents

This endpoint allows you to search for talents based on various filters. It utilizes a transaction-based pagination model for retrieving results.

```APIDOC
## POST /api/v1/search/talents

### Description
Searches for talents based on provided filters and returns a list of matching talents along with a transaction ID for pagination.

### Method
POST

### Endpoint
https://app.kalent.ai/api/v1/search/talents

### Parameters
#### Request Body
- **filters** (array) - Required - An array of filter objects to apply to the search.
  - **filterType** (string) - Required - The type of filter (e.g., JOB_TITLE, SKILL).
  - **value** (string) - Required - The value for the filter.
  - **isRequired** (boolean) - Required - Whether this filter is mandatory.
  - **isExcluded** (boolean) - Required - Whether to exclude talents matching this filter.
  - **isExactMatch** (boolean) - Required - Whether the match must be exact.
- **relatedSearchTransactionIds** (array) - Optional - An array of transaction IDs from previous searches to paginate results.

### Request Example
```json
{
  "filters": [
    { "filterType": "JOB_TITLE", "value": "Software Engineer", "isRequired": true, "isExcluded": false, "isExactMatch": false }
  ],
  "relatedSearchTransactionIds": ["tx_aaa111"]
}
```

### Response
#### Success Response (200)
- **talents** (array) - A list of talents matching the search criteria.
  - **name** (string) - Talent's name.
  - **email** (string) - Talent's email address.
  - **phone** (string) - Talent's phone number.
  - **linkedinProfileUrl** (string) - URL to the talent's LinkedIn profile.
  - **githubProfileUrl** (string) - URL to the talent's GitHub profile.
  - **websiteUrl** (string) - URL to the talent's personal website.
  - **summary** (string) - A brief summary of the talent.
  - **skills** (array) - List of skills the talent possesses.
  - **certifications** (array) - List of certifications the talent holds.
    - **name** (string) - Certification name.
    - **organizationName** (string) - Issuing organization.
    - **startDate** (string) - Issue date.
    - **endDate** (string) - Expiry date.
  - **estimationCount** (number) - Estimated total number of talents matching the query.
  - **searchTransactionId** (string) - Unique identifier for this search transaction.
- **error** (object) - Error details, present when `success` is `false`.
  - **code** (string) - Machine-readable error code.
  - **message** (string) - Human-readable error description.
  - **debugTrackingCode** (string) - Unique tracking code for this request.
  - **issues** (object[]) - Zod validation details.
  - **details** (object) - Rate limit details.
    - **window** (string) - The time window that was exceeded.
    - **limit** (number) - Maximum number of requests allowed in this window.
    - **current** (number) - Number of requests already made in this window.

#### Response Example
```json
{
  "talents": [
    {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "phone": "123-456-7890",
      "linkedinProfileUrl": "https://linkedin.com/in/janedoe",
      "githubProfileUrl": "https://github.com/janedoe",
      "websiteUrl": "https://janedoe.com",
      "summary": "Experienced Software Engineer with a passion for building scalable applications.",
      "skills": ["Python", "JavaScript", "AWS"],
      "certifications": [
        {
          "name": "AWS Certified Solutions Architect",
          "organizationName": "Amazon Web Services",
          "startDate": "2022-01-01",
          "endDate": "2025-01-01"
        }
      ]
    }
  ],
  "estimationCount": 150,
  "searchTransactionId": "tx_bbb222"
}
```

### Error Handling
- **validation_error**: Indicates an issue with the request payload validation.
- **too_many_search_transactions**: Indicates that the limit for search transactions has been exceeded.
- **missing_api_key**: Indicates that the API key is missing from the request.
- **invalid_api_key**: Indicates that the provided API key is invalid.
- **rate_limit_exceeded**: Indicates that the rate limit for the API has been exceeded.
- **internal_error**: Indicates an unexpected internal server error.
```

--------------------------------

### Search Talents API

Source: https://docs.kalent.ai/api-reference/search-talents

This endpoint allows you to search for talents based on various filters. It supports filtering by job title, industry, and more. The response includes a list of matching talents or an error if the request is invalid or exceeds limits.

```APIDOC
## POST /api/v1/search/talents

### Description
Searches for talents based on provided filters. Returns a list of matching talents or an error.

### Method
POST

### Endpoint
https://app.kalent.ai/api/v1/search/talents

### Parameters
#### Query Parameters
- **theme** (string) - Optional - Specifies the theme for the search results. Currently, only `null` is supported.

#### Request Body
- **filters** (array) - Required - An array of filter objects to refine the search.
  - **filterType** (string) - Required - The type of filter (e.g., "JOB_TITLE", "INDUSTRY").
  - **value** (string) - Required - The value to filter by.
  - **isRequired** (boolean) - Required - Whether this filter is mandatory.
  - **isExcluded** (boolean) - Required - Whether to exclude results matching this filter.
  - **isExactMatch** (boolean) - Required - Whether the match must be exact.
- **relatedSearchTransactionIds** (array) - Optional - A list of transaction IDs to relate this search to. Maximum 100 IDs allowed.

### Request Example
```json
{
  "filters": [
    {
      "filterType": "JOB_TITLE",
      "value": "Software Engineer",
      "isRequired": true,
      "isExcluded": false,
      "isExactMatch": false
    }
  ],
  "relatedSearchTransactionIds": ["tx_1", "tx_2", "...", "tx_101"]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the search results if successful.
  - **talents** (array) - A list of talent objects.
  - **nextPageToken** (string) - Token for paginating to the next page of results.

#### Response Example (Success)
```json
{
  "success": true,
  "data": {
    "talents": [
      {
        "id": "talent_123",
        "name": "Jane Doe",
        "jobTitle": "Software Engineer",
        "industry": "Technology"
      }
    ],
    "nextPageToken": "next_page_token_abc"
  }
}
```

#### Error Response (400 Bad Request)
- **success** (boolean) - Always false for errors.
- **error** (object) - Contains error details.
  - **code** (string) - Error code (e.g., "too_many_search_transactions").
  - **message** (string) - Human-readable error message.
  - **debugTrackingCode** (string) - A unique code for debugging purposes.

#### Response Example (Too Many Transactions)
```json
{
  "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"
  }
}
```
```

--------------------------------

### API Response: Rate Limit Exceeded (429)

Source: https://docs.kalent.ai/api-reference/search-talents

This error is returned when the API request rate limit is exceeded. The response includes details about the time window, the limit, and the current number of requests made.

```json
{
  "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
    }
  }
}
```

--------------------------------

### Define Company Name Filter

Source: https://docs.kalent.ai/api-reference/search-talents

Configures a filter to search for candidates by their current or past employers. The value field accepts the name of the company.

```json
{
  "filterType": "COMPANY_NAME",
  "value": "Google",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Filter by Company Industry (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet shows how to filter job searches by industry sector. The 'value' field takes a string representing the industry, with a reference available for accepted values.

```json
{
  "filterType": "COMPANY_INDUSTRY",
  "value": "software development",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Filter by Education Degree (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet illustrates filtering job searches based on the highest education degree obtained. Accepted values include 'bachelors', 'masters', and 'doctorates'.

```json
{
  "filterType": "EDUCATION_DEGREE",
  "value": "masters",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Duration in Job Filter

Source: https://docs.kalent.ai/api-reference/search-talents

Filter search results by the tenure in the current or last role.

```APIDOC
## DURATION_IN_JOB Filter

### Description
Search by tenure in current or last role.

### Parameters
#### Query Parameters
- **filterType** (string) - Required - `DURATION_IN_JOB`
- **value** (string) - Required - One of: `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, `30-100` (in years).
- **isRequired** (boolean) - Optional - Indicates if the filter is required.
- **isExcluded** (boolean) - Optional - Indicates if the filter should be excluded.
- **isExactMatch** (boolean) - Optional - Indicates if an exact match is required.

### Request Example
```json
{
  "filterType": "DURATION_IN_JOB",
  "value": "1-3",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

### Response
#### Success Response (200)
- **filterType** (string) - The type of filter applied.
- **value** (string) - The duration range used for filtering.
- **isRequired** (boolean) - Indicates if the filter is required.
- **isExcluded** (boolean) - Indicates if the filter is excluded.
- **isExactMatch** (boolean) - Indicates if an exact match is required.

#### Response Example
```json
{
  "filterType": "DURATION_IN_JOB",
  "value": "1-3",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```
```

--------------------------------

### Rate Limit Error

Source: https://docs.kalent.ai/api-reference/search-talents

Details the error response when the API rate limit is exceeded.

```APIDOC
## Rate Limit Error

### Description
This section details the error response when the API rate limit is exceeded.

### Method
POST

### Endpoint
https://app.kalent.ai/api/v1/search/talents

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

##### Response Example
```json
{
  "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
    }
  }
}
```
```

--------------------------------

### Search Talents API - Specific Filter Value Details

Source: https://docs.kalent.ai/api-reference/accepted-filter-values

Provides detailed accepted values for specific filter types used in the Search Talents API, including `YEARS_OF_EXPERIENCE`, `COMPANY_SIZE`, `EDUCATION_DEGREE`, `DURATION_IN_JOB`, `LANGUAGE`, and `SENIORITY`.

```APIDOC
## Search Talents API - Specific Filter Value Details

This section provides the accepted values for several filter types used in the Search Talents API.

### YEARS_OF_EXPERIENCE
Accepted values: `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, `30-100`

### COMPANY_SIZE
Accepted values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`

### EDUCATION_DEGREE
Accepted values: `bachelors`, `masters`, `doctorates`

### DURATION_IN_JOB
Accepted values: `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, `30-100`

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

### SENIORITY
Accepted values: `Freelance`

### history Filter
Applies to `JOB_TITLE` and `COMPANY_NAME`. Accepted values: `PAST`, `CURRENT`, `CURRENT_OR_PAST`
```

--------------------------------

### Filter by Graduation Year (JSON)

Source: https://docs.kalent.ai/api-reference/search-talents

This JSON snippet shows how to filter job searches by graduation year. The 'value' field should be a four-digit year.

```json
{
  "filterType": "GRADUATION_YEAR",
  "value": "2020",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
```

--------------------------------

### Define Language Filter

Source: https://docs.kalent.ai/api-reference/search-talents

Configures a filter to search for candidates by spoken language. The value should be a lowercase string representing the language name.

```json
{
  "filterType": "LANGUAGE",
  "value": "french",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}
```
Tokens:
Raw