Skip to content

Employee Search API: Find People From a Written Prompt

Instead of assembling a stack of filters and checking profiles by hand, you can describe the people you need in ordinary language and receive a ranked set of matching profiles as JSON. This guide explains what the Employee Search API accepts, what it returns, how to write prompts that behave predictably, and how the credit cost applies.

Why prompt-based people search is worth considering

Manual people search tends to grow sideways. A role is added, then a seniority band, a country, an industry, a company size, and a handful of skills. Each new condition narrows the pool, and you still have to open profiles to judge whether the match is real.

A prompt-based API replaces that filter assembly with a single description. You state the kind of person you want, and the service performs the search and orders the results by how well they fit. The trade-off is important: you gain convenience and ranking, but you give up the guarantee that every condition is applied as a hard database filter. For exploratory sourcing, that is often a good trade. For compliance-grade exact matching, it is not.

How the search flow works

The flow is short: a natural-language prompt goes in, and a ranked list of employee profiles comes back. You do not need to build a filter engine or merge several search criteria yourself.

The service interprets the description, looks for profiles that fit, and orders them by relevance. Because ranking is involved, a strong adjacent match can appear alongside the exact title you asked for. A search for senior engineers, for example, may include a principal engineer when the rest of the profile is a close fit.

Quickstart: a first search from Python

You need an API key and a description of the people you want. Install the requests package, then send a GET request to the agentic search endpoint with your key in the Authorization header and your description in the prompt parameter.

The example below searches for senior machine learning engineers living in Austin, Texas, who work at fintech companies. The response is parsed as JSON, and the loop prints each profile's name, current title, and company. The exact request code is provided in the accompanying code module, and the sample output module shows the printed shape: a name, a title, and a company for each match.

Reading the response: stable fields versus prompt-dependent fields

The response object carries the prompt you sent, a count of profiles found, and a results array. Each search returns up to 20 profiles, ranked by relevance.

A small set of fields is always present on a profile: id, full_name, company_name, and active_experience_title. Other fields depend on what your prompt asked for. A location constraint brings location fields into the response; a follower threshold brings followers_count. Treat the profile shape as dynamic and code defensively rather than assuming a fixed field list.

One case deserves special attention. When nothing matches, results is an empty array. That is a valid response, not an error, and the request is not charged. Distinguish it from a failed request, which is also not charged and is retried automatically up to three times before an error is returned.

Parameters and authentication at a glance

The API uses a single GET endpoint. You authenticate with your API key and pass search options as query parameters.

  • prompt: required. The natural-language description of the employees you want, up to 5,000 characters.
  • limit: deprecated and no longer has any effect. It is still accepted with values from 1 to 100 for backward compatibility, but every search returns up to 20 profiles ranked by relevance.
  • tag: optional. Attaches your own identifier to a request. The tag is returned with the response headers and does not change the search itself.
  • Authentication: required on every request. Pass your API key in the Authorization header.

The endpoint path, header format, and parameter examples are preserved exactly in the accompanying code modules.

Writing prompts that return useful results

A good prompt is specific enough to describe the target without piling on requirements. A practical checklist:

  1. Lead with role and seniority, then add one strong signal such as company type or location.
  2. Write in plain language. "Senior backend engineers at SaaS companies in Germany" works better than an imitation of a complex filter query.
  3. Be explicit about location. Use wording such as "living in" or "based in" when the person's location matters; company headquarters and employee location are separate signals.
  4. Describe the company by characteristics rather than by name. Searching for a specific named employer is not reliably supported during the beta, so prefer industry, size, or stage.
  5. Avoid negative conditions. Prompts such as "engineers who are not managers" may not be interpreted consistently.
  6. Expect relevance matches, not exact filters. A senior search can surface a principal engineer when the profile is otherwise a strong fit.
  7. Start broad, then refine. If nothing comes back, remove a condition or loosen the wording before adding more criteria. For more precision, run a second search from a different angle rather than stacking requirements into one prompt.
  8. Capitalization, minor typos, and non-English prompts are supported, and a normal question works as well as a keyword list.

The API can also search on signals such as skills, company size, recent job changes, career moves, follower counts, and separate employee and company locations.

How credits are charged

A successful request that returns at least one matching profile costs 3,750 API credits. Requests that return no matching profiles are free, and failed requests are not charged. The monetary cost depends on your plan and the number of credits it includes.

Because empty results are free, a broad first pass followed by a narrower second pass is a reasonable way to work. You are not billed for a search that finds nothing.

Getting started

The Employee Search API offers a direct route from a written description to a ranked set of employee profiles, without building your own search and filtering system. For the full list of parameters, response fields, prompt examples, and current limitations, see the Employee Search API documentation. To begin, create an account and start exploring the API.

Response field map
FieldLevelPresenceMeaning
promptTop levelAlwaysThe natural-language query you sent.
result_countTop levelAlwaysNumber of profiles returned, up to 20 per search.
resultsTop levelAlwaysMatching employee profiles; an empty array when nothing matches.
idProfileAlwaysProfile identifier.
full_nameProfileAlwaysPerson's full name.
company_nameProfileAlwaysCurrent company name.
active_experience_titleProfileAlwaysCurrent role title.
location fieldsProfileWhen prompt includes locationAdded by a location constraint.
followers_countProfileWhen prompt includes a follower thresholdAdded by a follower threshold.

Field presence beyond the core set depends on the prompt; treat the response as dynamic.

Prompt-writing checklist
PracticeDoAvoid
SignalsTwo or three important signalsStacking many requirements
WordingPlain languageImitating a complex filter query
Location"Living in" or "based in"Assuming company HQ equals employee location
CompanyIndustry, size, or stageA specific named employer during the beta
NegativesPositive descriptions"Not a manager" style conditions
ExpectationRelevance matchesExact database filters
RefinementStart broad, then narrowAdding criteria after an empty result

These are practical prompt-writing guidelines, not guarantees of result composition.

Frequently asked questions

What is an Agentic Employee Search API?

It is a programmatic way to locate employee profiles: you supply a plain-language description of the people you want, and the service replies with profiles that fit, delivered as structured JSON rather than a rendered page.

What can I search for with the Agentic Employee Search API?

You can search by signals such as job title, seniority, skills, industry, company characteristics, and location, and you can combine several criteria in one prompt.

Does the Agentic Employee Search API use exact filters?

Not necessarily. Profiles are ranked by relevance rather than every part of the prompt being applied as a strict database filter. A search for senior engineers may return a principal engineer when the profile is a strong match.

How much does the Agentic Employee Search API cost?

A request that returns at least one result costs 3,750 API credits. Requests that return no results and failed requests are not charged.

Is an empty results array an error?

No. An empty results array is a valid response and the request is not charged. A failed request is different: it is retried automatically up to three times before an error is returned, and it is also not charged.

{
  "prompt": "Senior machine learning engineers living in Austin, Texas, working at fintech companies",
  "result_count": 2,
  "results": [
    {
      "id": 123456789,
      "full_name": "Alex Morgan",
      "active_experience_title": "Senior Machine Learning Engineer",
      "company_name": "ExamplePay",
      "location_country_iso2": "US",
      "experience": [
        {
          "company_id": 42,
          "company_name": "ExamplePay",
          "position_title": "Senior Machine Learning Engineer",
          "active_experience": 1,
          "management_level": "Senior"
        }
      ]
    },
    {
      "id": 987654321,
      "full_name": "Jordan Lee",
      "active_experience_title": "Principal Machine Learning Engineer",
      "company_name": "Fintech Labs",
      "location_country_iso2": "US",
      "experience": [
        {
          "company_id": 77,
          "company_name": "Fintech Labs",
          "position_title": "Principal Machine Learning Engineer",
          "active_experience": 1,
          "management_level": "Senior"
        }
      ]
    }
  ]
}