Talent search (L1)
Search talents
Find professional profiles matching a set of filters.
POST
Search talents
First time? Set up Authentication
Learn how to authenticate your API requests with your API key.
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
JOB_TITLE
JOB_TITLE
Search by job title or role.
LOCATION
LOCATION
Search by geographic location.
YEARS_OF_EXPERIENCE
YEARS_OF_EXPERIENCE
Search by years of professional experience.
SKILL
SKILL
Search by technical or soft skill.
KEYWORD
KEYWORD
Free-text search across the entire profile.
LANGUAGE
LANGUAGE
Search by spoken language.
Common values:
english, french, spanish, german, portuguese, mandarin, japanese, korean, arabic, hindi, italian, dutch, russian, turkish, polish, swedish.LANGUAGE_PROFICIENCY
LANGUAGE_PROFICIENCY
Search by language proficiency level.
COMPANY_NAME
COMPANY_NAME
Search by current or past employer.
COMPANY_SIZE
COMPANY_SIZE
Search by employer company size.
COMPANY_INDUSTRY
COMPANY_INDUSTRY
Search by employer industry sector.
See the full list of accepted industries in the industry values reference.
EDUCATION_DEGREE
EDUCATION_DEGREE
Search by highest education level.
EDUCATION_SCHOOL_NAME
EDUCATION_SCHOOL_NAME
Search by school or university.
CERTIFICATION_NAME
CERTIFICATION_NAME
Search by professional certification.
SENIORITY
SENIORITY
Search by contract type.
TIMEZONE
TIMEZONE
Search by the timezone of the talent’s location.
IS_OPEN_TO_WORK
IS_OPEN_TO_WORK
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.DURATION_IN_JOB
DURATION_IN_JOB
Search by tenure in current or last role.
GRADUATION_YEAR
GRADUATION_YEAR
Search by graduation year.
LINKEDIN_RELATIONS_DEGREE
LINKEDIN_RELATIONS_DEGREE
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
- First request — call the endpoint with your filters. The response includes a
searchTransactionIdand up to 10 matching talents. - Next page — send the same filters again, but add the previous
searchTransactionIdto therelatedSearchTransactionIdsarray. The API will exclude all talents that were already returned and give you the next batch. - Subsequent pages — keep accumulating
searchTransactionIdvalues in the array. Each new request excludes all talents from every prior transaction. The array accepts at most 300 IDs.
Response examples
200 — Success
200 — Success
Request
Response
400 — Validation error
400 — Validation error
Returned when the request body does not match the expected schema.
Request
Response
400 — Too many search transactions
400 — Too many search transactions
Returned when
relatedSearchTransactionIds contains more than 300 entries. Refine your search filters instead of paginating further.Request
Response
401 — Authentication error
401 — Authentication error
Returned when the API key is missing or invalid.
Request
Response (missing key)
Response (invalid key)
429 — Rate limit exceeded
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
422 — Unsupported location
422 — Unsupported location
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
504 — Search engine timeout
504 — Search engine timeout
Returned when the search engine request times out. Retry the same request; include the
debugTrackingCode when contacting support.Response
500 — Server error
500 — Server error
Returned when an unexpected error occurs. Include the
debugTrackingCode when contacting support.Response
Industry values
Full list of accepted industry values (147)
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
