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>"
  ]
}
'

{
  "has_more": true,
  "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
}

People Search

Search for people

Search for people matching filters with cursor-based pagination.

First page: send filters — returns up to 25 results, a next_cursor (opaque pagination token), has_more, and total_count.

Next pages: pass back the next_cursor from the previous response — returns the next 25 results and a new next_cursor. Repeat while has_more is true.

The cursor is opaque; do not introspect it. Invalid or expired cursors return 400; start a fresh search.

Each page consumes 1 credit per result returned.

POST

people

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>"
  ]
}
'

{
  "has_more": true,
  "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 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:

["C"]

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

Deprecated. Ignored by the server. Use next_cursor.

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:

["c4d7e6f3-2345-4bcd-aef0-123456789abc"]

industry_includes_ids

string[] | null

Industry IDs to include.

Resolve via Search industries and pass the returned id.

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 refinement hint forwarded to the underlying provider. Best-effort — not all providers honor this field, and matches that ignore it may still be returned.

Example:

"AI sales"

last_name

string

Filter by last name

Example:

"Alderson"

next_cursor

string

Opaque pagination token returned by the previous response's next_cursor. Pass it back unchanged to fetch the next page. Omit on first-page calls. Invalid or expired cursors return 400.

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

deprecated

Deprecated and unreliable: providers do not consistently honor seniority filtering. Kept for backward compatibility.

seniority_includes

string[] | null

deprecated

Deprecated and unreliable: providers do not consistently honor seniority filtering. Kept for backward compatibility.

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:

["6 to 10 years"]

Response

has_more

boolean

required

True when more pages can be fetched by passing next_cursor back.

results

object[] | null

required

Search results for this page (up to 25)

Show child attributes

cursor

string

Deprecated. Mirrors next_cursor. Use next_cursor instead.

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

Opaque pagination token. Pass it back unchanged to fetch the next page. Null when there are no more results.

total_count

integer<int64>

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

Example:

132

Extract a person's profile List personas