Skip to main content
POST
Search talents

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. The search runs in gate mode when mode is omitted. See Search modes. Only ready profiles are returned: talents that are already up to date, or that were synchronously refreshed and passed refiltering. The search keeps fetching until nbToFetch ready profiles are found or an internal page/time budget is reached; when fewer profiles are delivered the response is still 200 and resultCompleteness says why. An asynchronous refresh is omitted from this response and can appear on a later call.

Request body

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:
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. Maximum 300 IDs. See Pagination below.
number
default:"10"
How many ready talent profiles to return, between 1 and 10. One credit is charged per profile actually returned. When fewer than nbToFetch ready profiles can be delivered, the response is still 200 and resultCompleteness explains why.
string
default:"gate"
Search engine mode. One of gate or rank. If omitted, gate is used. See Search modes.
integer
default:"1"
Profiles last updated more than this many months ago are live-refreshed before being returned. More recent profiles are returned as is. Integer between 1 and 6. A higher value makes the search faster, but returns profiles that were updated less recently. The default of 1 month is unchanged when the field is omitted. Values outside 1–6 or non-integers return a 400 validation_error.

Search modes

mode is gate or rank. If omitted, gate is used. The same two modes apply to this endpoint, to talent-pool estimation, and to MCP talent search by filters. Rank mode treats all filters independently of their type. Each required filter that is not matched eliminates the profile. Optional filters are treated as a bonus: profiles can fail them, but they receive a bonus for each optional filter they match. This bonus influences the order in which the search engine returns profiles, so that profiles that match the most optional filters come first. Gate mode follows the same logic as rank mode, with one exception: for each filter type present in the query, a profile that matches none of the filters of that type is eliminated from the results, even if they are all optional. This mode is more restrictive by construction, but also more intuitive in an application, where the intent of adding several optional filters on the same field often translates into an “OR” between them. Qualified search always runs in gate mode. The gate estimate from talent-pool estimation is therefore the one that matches the qualified search pool.

Filter types

Search by job title or role.
Search by geographic location.
Search by years of professional experience.
Search by technical or soft skill.
Free-text search across the entire profile.
Search by spoken language.Common values: english, french, spanish, german, portuguese, mandarin, japanese, korean, arabic, hindi, italian, dutch, russian, turkish, polish, swedish.
Search by language proficiency level.
Search by current or past employer.
Search by employer company size.
Search by employer industry sector.See the full list of accepted industries in the industry values reference.
Search by highest education level.
Search by school or university.
Search by professional certification.
Search by contract type.
Search by the timezone of the talent’s location.
Search for talents we estimate are likely open to new opportunities.Omit the filter to ignore open-to-work status entirely.Available for talents located in France only: the filter applies only when the search also has a LOCATION in France that is not excluded. Otherwise it is ignored.
Search by tenure in current or last role.
Search by graduation year.
Search by relationship to your connected LinkedIn account.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.

Response

Successful responses carry two headers:
boolean
Whether the request completed without errors.
object
Present when success is true.
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. The array accepts at most 300 IDs.
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
Response
Returned when the request body does not match the expected schema.
Request
Response
Returned when relatedSearchTransactionIds contains more than 300 entries. Refine your search filters instead of paginating further.
Request
Response
Returned when the API key is missing or invalid.
Request
Response (missing key)
Response (invalid key)
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
Returned when a LOCATION filter cannot be resolved. Remove that location or rephrase it. Retrying the same value will not succeed, and no credits are consumed.
Response
Returned when the search engine request times out. Retry the same request; include the debugTrackingCode when contacting support.
Response
Returned when an unexpected error occurs. Include the debugTrackingCode when contacting support.
Response

Industry values

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