Skip to main content
POST
/
v2
/
people
/
search
Search for people
curl --request POST \
  --url https://api.tamtam.ai/api/v2/people/search \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "canonical_job_titles_excludes_ids": [
    "<string>"
  ],
  "canonical_job_titles_includes_ids": [
    "<string>"
  ],
  "company_headcounts": [
    "<string>"
  ],
  "company_hq_countries": [
    "<string>"
  ],
  "company_linkedin_ids": [
    "<string>"
  ],
  "countries": [
    "<string>"
  ],
  "cursor": "<string>",
  "first_name": "<string>",
  "industry_excludes_ids": [
    "<string>"
  ],
  "industry_includes_ids": [
    "<string>"
  ],
  "job_titles_excludes": [
    "<string>"
  ],
  "job_titles_includes": [
    "<string>"
  ],
  "keywords": "<string>",
  "last_name": "<string>",
  "next_cursor": "<string>",
  "prompt": "<string>",
  "recently_changed_jobs": true,
  "seniority_excludes": [
    "<string>"
  ],
  "seniority_includes": [
    "<string>"
  ],
  "years_of_experience": [
    "<string>"
  ]
}
'
{
  "results": [
    {
      "contact_id": "<string>",
      "first_name": "<string>",
      "job_title": "<string>",
      "last_name": "<string>",
      "linkedin_profile_id": "<string>",
      "profile_url": "<string>",
      "company_linkedin_id": "<string>",
      "company_logo_url": "<string>",
      "company_name": "<string>",
      "location": "<string>",
      "profile_image_url": "<string>",
      "summary": "<string>"
    }
  ],
  "cursor": "<string>",
  "filter_reasoning": "<string>",
  "next_cursor": "<string>",
  "total_count": 123
}

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 size ranges

Example:
["11-50"]
​
company_hq_countries
string[] | null

Company HQ country codes

Example:
["FR"]
​
company_linkedin_ids
string[] | null

LinkedIn company IDs to filter by

Example:
["104924588"]
​
countries
string[] | null

Country codes to filter by

Example:
["FR"]
​
cursor
string

Search session identifier returned by the first call. Pass it back unchanged for every subsequent page.

​
first_name
string

Filter by first name

Example:

"Elliot"

​
industry_excludes_ids
string[] | null

Industry IDs to exclude

Example:
["c4d7e6f3-2345-4bcd-aef0-123456789abc"]
​
industry_includes_ids
string[] | null

Industry IDs to include

Example:
["b3c6f5e2-1234-4abc-9def-0123456789ab"]
​
job_titles_excludes
string[] | null

Job titles to exclude

Example:
["Intern"]
​
job_titles_includes
string[] | null

Job titles to include

Example:
["Head of Sales"]
​
keywords
string

Free-text keyword search

Example:

"AI sales"

​
last_name
string

Filter by last name

Example:

"Alderson"

​
next_cursor
string

Page token returned by the previous call. Pass it back to fetch the next page of results.

​
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"

​
recently_changed_jobs
boolean

Only include people who recently changed jobs

Example:

true

​
seniority_excludes
string[] | null

Seniority levels to exclude

​
seniority_includes
string[] | null

Seniority levels to include

Example:
["head"]
​
years_of_experience
string[] | null

Years of experience ranges

Example:
["6_10"]

Response

OK

​
results
object[] | null
required

Search results for this page (up to 25)

​
cursor
string

Search session identifier. Returned on the first page only — pass it back unchanged in every subsequent request.

Example:

"sess_01HXYZ"

​
filter_reasoning
string

When Prompt is used, explains how the AI interpreted the prompt into filters. Returned on the first page only.

Example:

"Interpreted as Head of Sales, country FR"

​
next_cursor
string

Page token for the next page. Null when there are no more results.

Example:

"page_2"

​
total_count
integer<int64>

Total number of matching results. Returned on the first page only.

Example:

132