Skip to main content
POST
/
v1
/
search
/
talents
Search talents
curl --request POST \
  --url https://app.kalent.ai/api/v1/search/talents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filters": [
    {
      "filterType": "<string>",
      "value": "<string>",
      "isRequired": true,
      "isExcluded": true,
      "isExactMatch": true,
      "radius": 123,
      "history": "<string>"
    }
  ],
  "relatedSearchTransactionIds": [
    "<string>"
  ]
}
'
{
  "success": true,
  "data": {
    "talents": [
      {
        "id": "<string>",
        "firstname": "<string>",
        "lastname": "<string>",
        "gender": "<string>",
        "city": "<string>",
        "country": "<string>",
        "jobTitle": "<string>",
        "summary": "<string>",
        "state": "<string>",
        "headline": "<string>",
        "photoUrl": "<string>",
        "linkedinUrl": "<string>",
        "currentOrganization": {
          "id": "<string>",
          "name": "<string>",
          "logoUrl": "<string>"
        },
        "experiences": [
          {
            "organizationName": "<string>",
            "title": "<string>",
            "startDate": "<string>",
            "endDate": "<string>",
            "description": "<string>",
            "isCurrent": true,
            "organization": {
              "logoUrl": "<string>",
              "name": "<string>"
            }
          }
        ],
        "educations": [
          {
            "schoolName": "<string>",
            "schoolLogo": "<string>",
            "summary": "<string>",
            "degrees": [
              "<string>"
            ],
            "majors": [
              "<string>"
            ],
            "minors": [
              "<string>"
            ],
            "startDate": "<string>",
            "endDate": "<string>",
            "schoolDomain": "<string>"
          }
        ],
        "skills": [
          "<string>"
        ],
        "interests": [
          "<string>"
        ],
        "languages": [
          {
            "name": "<string>",
            "proficiency": "<string>"
          }
        ],
        "certifications": [
          {
            "name": "<string>",
            "organizationName": "<string>",
            "startDate": "<string>",
            "endDate": "<string>"
          }
        ]
      }
    ],
    "estimationCount": 123,
    "searchTransactionId": "<string>",
    "pendingRefreshCount": 123
  },
  "error": {
    "code": "<string>",
    "message": "<string>",
    "debugTrackingCode": "<string>",
    "issues": [
      {}
    ],
    "details": {
      "window": "<string>",
      "limit": 123,
      "current": 123
    }
  }
}

First time? Set up Authentication

Learn how to authenticate your API requests with your API key.
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

​
filters
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:
​
relatedSearchTransactionIds
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 below.

​
Filter types

Search by job title or role.
FieldValue
filterTypeJOB_TITLE
valueFree text — e.g. "Product Designer", "Software Engineer"
{
  "filterType": "JOB_TITLE",
  "value": "Product Designer",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false,
  "history": "CURRENT"
}
Search by geographic location.
FieldValue
filterTypeLOCATION
valueCity or country — e.g. "Paris", "United States"
radiusOptional. Kilometers around the location.
{
  "filterType": "LOCATION",
  "value": "San Francisco",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false,
  "radius": 50
}
Search by years of professional experience.
FieldValue
filterTypeYEARS_OF_EXPERIENCE
valueOne of: 0-1, 1-3, 3-5, 5-10, 10-15, 15-20, 20-30, 30-100
{
  "filterType": "YEARS_OF_EXPERIENCE",
  "value": "5-10",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}
Search by technical or soft skill.
FieldValue
filterTypeSKILL
valueFree text — e.g. "React", "Project Management"
{
  "filterType": "SKILL",
  "value": "React",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}
Free-text search across the entire profile.
FieldValue
filterTypeKEYWORD
valueFree text — e.g. "Figma", "B2B SaaS"
{
  "filterType": "KEYWORD",
  "value": "B2B SaaS",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by spoken language.
FieldValue
filterTypeLANGUAGE
valueLowercase 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.
{
  "filterType": "LANGUAGE",
  "value": "french",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}
Search by language proficiency level.
FieldValue
filterTypeLANGUAGE_PROFICIENCY
valueProficiency level or language+level combination
{
  "filterType": "LANGUAGE_PROFICIENCY",
  "value": "native",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by current or past employer.
FieldValue
filterTypeCOMPANY_NAME
valueFree text — e.g. "Google", "McKinsey"
{
  "filterType": "COMPANY_NAME",
  "value": "Google",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false,
  "history": "CURRENT_OR_PAST"
}
Search by employer company size.
FieldValue
filterTypeCOMPANY_SIZE
valueOne of: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+
{
  "filterType": "COMPANY_SIZE",
  "value": "51-200",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by employer industry sector.
FieldValue
filterTypeCOMPANY_INDUSTRY
valueIndustry string — e.g. "software development", "financial services", "hospitals and health care"
See the full list of accepted industries in the industry values reference.
{
  "filterType": "COMPANY_INDUSTRY",
  "value": "software development",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by highest education level.
FieldValue
filterTypeEDUCATION_DEGREE
valueOne of: bachelors, masters, doctorates
{
  "filterType": "EDUCATION_DEGREE",
  "value": "masters",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by school or university.
FieldValue
filterTypeEDUCATION_SCHOOL_NAME
valueFree text — e.g. "MIT", "HEC Paris"
{
  "filterType": "EDUCATION_SCHOOL_NAME",
  "value": "HEC Paris",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by professional certification.
FieldValue
filterTypeCERTIFICATION_NAME
valueFree text — e.g. "AWS Certified", "PMP"
{
  "filterType": "CERTIFICATION_NAME",
  "value": "AWS Certified",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by contract type.
FieldValue
filterTypeSENIORITY
valueCurrently only Freelance
{
  "filterType": "SENIORITY",
  "value": "Freelance",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}
Search by tenure in current or last role.
FieldValue
filterTypeDURATION_IN_JOB
valueOne of: 0-1, 1-3, 3-5, 5-10, 10-15, 15-20, 20-30, 30-100
{
  "filterType": "DURATION_IN_JOB",
  "value": "1-3",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by graduation year.
FieldValue
filterTypeGRADUATION_YEAR
valueFour-digit year — e.g. "2020"
{
  "filterType": "GRADUATION_YEAR",
  "value": "2020",
  "isRequired": false,
  "isExcluded": false,
  "isExactMatch": false
}
Search by relationship to your connected LinkedIn account.
FieldValue
filterTypeLINKEDIN_RELATIONS_DEGREE
valueOne of: 1st degree, invited
isExactMatchAlways 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.
{
  "filterType": "LINKEDIN_RELATIONS_DEGREE",
  "value": "1st degree",
  "isRequired": true,
  "isExcluded": false,
  "isExactMatch": false
}

​
Response

​
success
boolean
Whether the request completed without errors.
​
data
object
Present when success is true.
​
error
object
Error details, present when success is false.

​
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.
# 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"]
  }'
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 guide.

​
Response examples

Request
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
      }
    ]
  }'
Response
{
  "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
  }
}
Returned when the request body does not match the expected schema.
Request
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
      }
    ]
  }'
Response
{
  "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"
      }
    ]
  }
}
Returned when relatedSearchTransactionIds contains more than 100 entries. Refine your search filters instead of paginating further.
Request
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"]
  }'
Response
{
  "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"
  }
}
Returned when the API key is missing or invalid.
Request
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 (missing key)
{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
Response (invalid key)
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
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
{
  "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
    }
  }
}
Returned when the search engine request times out. Retry the same request; include the debugTrackingCode when contacting support.
Response
{
  "success": false,
  "error": {
    "code": "search_engine_timeout",
    "message": "The search request timed out. Please try again.",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}
Returned when an unexpected error occurs. Include the debugTrackingCode when contacting support.
Response
{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An error occurred during search talents",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

​
Industry values

accommodation services, food and beverage services, hospitality, administrative and support services, events services, facilities services, staffing and recruiting, construction, building construction, civil engineering, consumer services, non-profit organizations, education, e-learning providers, higher education, primary and secondary education, professional training and coaching, entertainment providers, performing arts and spectator sports, wellness and fitness services, farming, ranching, forestry, financial services, capital markets, investment banking, investment management, venture capital and private equity principals, banking, insurance, government administration, holding companies, hospitals and health care, medical practices, manufacturing, chemical manufacturing, pharmaceutical manufacturing, computers and electronics manufacturing, semiconductor manufacturing, food and beverage manufacturing, oil, gas, and mining, professional services, accounting, advertising services, business consulting and services, marketing services, design services, engineering services, it services and it consulting, computer and network security, it system custom software development, legal services, law practice, research services, real estate and equipment rental services, real estate, retail, online and mail order retail, retail apparel and fashion, technology, information and media, telecommunications, software development, internet marketplace platforms, social networking platforms, transportation, logistics, supply chain and storage, airlines and aviation, utilities, wholesale, marketing and advertising, management consulting, computer software, internet, hospital & health care, architecture & planning, oil & energy, publishing, logistics and supply chain, pharmaceuticalsAnd many more — the full list contains 500+ industry values from LinkedIn’s taxonomy.