Skip to main content
POST
Plan a large people search before running it

Authorizations

​
Authorization
string
header
required

Account API key passed in the Authorization header

Body

application/json
​
canonical_job_titles_excludes_ids
string[] | null

Canonical job title IDs to exclude

​
canonical_job_titles_includes_ids
string[] | null

Canonical job title IDs to include

​
company_headcounts
string[] | null

Company headcount band codes (single letter). A=self-employed, B=1-10, C=11-50, D=51-200, E=201-500, F=501-1000, G=1001-5000, H=5001-10000, I=10001+.

Example:
​
company_hq_countries
string[] | null

Company HQ country codes

Example:
​
company_linkedin_ids
string[] | null

LinkedIn company IDs to filter by

Example:
​
countries
string[] | null

Country codes to filter by

Example:
​
country_excludes
string[] | null

Country codes to exclude. Narrows a search rather than describing one, so it cannot be the only filter sent.

Example:
​
first_name
string

Filter by first name

Example:

"Elliot"

​
industry_excludes_ids
string[] | null

Industry IDs to exclude.

Resolve via Search industries and pass the returned id.

Example:
​
industry_includes_ids
string[] | null

Industry IDs to include.

Resolve via Search industries and pass the returned id.

Example:
​
job_titles_excludes
string[] | null

Job titles to exclude

Example:
​
job_titles_includes
string[] | null

Job titles to include

Example:
​
keywords
string

Free-text search over the whole profile: headline, About, every role's title and description, skills, education. A boolean expression — uppercase AND / OR, double quotes around phrases, parentheses for grouping, implicit AND between bare words — passed through to LinkedIn as written. Honored or the search fails: when no configured provider supports profile keywords, the request returns 503 rather than a page that ignores the expression.

Example:

"\"supply chain\" AND SAP"

​
last_name
string

Filter by last name

Example:

"Alderson"

​
persona_id
string

Search using one of your saved personas, which supplies the job titles, countries and seniority bands behind it. List them via List personas.

Any filter you also send explicitly overrides the persona's value for that field; combine it with company_linkedin_ids to search a persona within specific companies. Mutually exclusive with prompt. One persona per call — to search several, call once per persona.

Example:

"b3c6f5e2-1234-4abc-9def-0123456789ab"

​
profile_languages
string[] | null

Languages the person's LinkedIn profile is written in (ISO 639-1: en, fr, de, es, it, nl, pt), ORed. The language of the profile, not of the person. Include only: a language cannot be excluded. Omitted, the persona's languages apply when a persona is given.

Example:
​
prompt
string

Free-text search prompt (e.g. 'CTOs at fintech startups in France'). Mutually exclusive with filter fields.

Example:

"Head of Sales at AI startups in France"

​
provider
enum<string>

Run the search on one specific people-search source, with no fallback to another. Omit to let Tamtam choose, which is the default and falls back when a source is unavailable.

endor does not support keywords: a search carrying them is refused with a 400 rather than run without them. It also ignores years_of_experience.

Read on the first page only. Later pages always stay on the source that served the first, since next_cursor belongs to it.

Available options:
endor,
bespin
Example:

"endor"

​
recently_changed_jobs
boolean

Only include people who recently changed jobs

Example:

true

​
seniority_excludes
string[] | null
deprecated

Deprecated and IGNORED. There is no exclude form: the filter keeps the bands you ask for plus everyone it cannot classify, which an exclude list cannot express. Use seniority_includes.

​
seniority_includes
string[] | null

Seniority bands to keep, derived from each person's job title. Allowed values: 'Owner / Partner', 'CXO', 'Vice President', 'Director', 'Experienced Manager', 'Senior', 'Entry Level', 'In Training'. A person whose title carries no seniority signal is kept rather than dropped, so this narrows results without discarding the unlabelled. 'Entry Level Manager' is accepted and behaves as 'Experienced Manager'; 'Strategic' is accepted and has no effect.

Example:
​
use_persona_ai_extension
boolean

Whether this search widens the persona with Tamtam's AI extension of it: extra job titles inferred from the roles that actually convert for you, held outside the persona's own definition so they never appear in it.

Omit to use whatever the persona is set to — the default, and what the app itself does. Send false to search only the job titles written on the persona; the extension is recomputed periodically, so this is the setting that makes a search reproducible. Send true to widen even when the persona has the extension switched off. Sending true has no effect on a persona for which no extension has been computed yet.

Requires persona_id.

Example:

false

​
years_of_experience
string[] | null

Refinement hint forwarded to the underlying provider. Allowed values: 'Less than 1 year', '1 to 2 years', '3 to 5 years', '6 to 10 years', 'More than 10'. Best-effort — not all providers honor this field, and matches that ignore it may still be returned.

Example:

Response

Accepted

​
contacts_list_ids
string[] | null
required

The contacts lists the job has filled so far, in order, 10,000 people each. Empty when no list was asked for.

​
created_at
string<date-time>
required

When the job was created

​
job_id
string
required

The job's ID, to poll it, read its results or stop it

Example:

"b3c6f5e2-1234-4abc-9def-0123456789ab"

​
max_results
integer<int64>
required

The cap the job stops at. 0 while planning.

Example:

100000

​
plan
object[] | null
required

The searches the job was split into, in the order they run. Empty while planning.

​
saved_count
integer<int64>
required

How many distinct people the job has saved so far

Example:

12500

​
searches
integer<int64>
required

How many searches the job was split into. 1 for a search the source serves whole.

Example:

24

​
searches_failed
integer<int64>
required

How many of those failed after repeated retries. What they saved before failing is kept.

Example:

0

​
searches_finished
integer<int64>
required

How many of those have run to their end

Example:

10

​
status
enum<string>
required

planning while the search is split into searches the source can serve whole. planned once the plan is ready: a job started with the plan endpoint waits there until you run it, one started to run goes straight on. running while pages are collected. completed when every search ran to its end or max_results was reached. stopped when you stopped it. out_of_credits when the account ran out of credits. failed when it could not go on, see error. Whatever ends a job, what it saved is kept.

Available options:
planning,
planned,
running,
completed,
stopped,
out_of_credits,
failed
Example:

"running"

​
unreachable_count
integer<int64>
required

People the search matches that no split could bring within reach of the source, and that the job will therefore not collect. See the operation description.

Example:

0

​
error
string

Why a failed job stopped: planning_failed, search_failed or start_failed

Example:

"planning_failed"

​
finished_at
string<date-time>

When the job ended, whatever the reason

​
provider
string

The source the job was pinned to, when one was asked for

Example:

"endor"