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": [
    "C"
  ],
  "company_hq_countries": [
    "FR"
  ],
  "company_linkedin_ids": [
    "104924588"
  ],
  "countries": [
    "FR"
  ],
  "country_excludes": [
    "BE"
  ],
  "cursor": "<string>",
  "first_name": "Elliot",
  "industry_excludes_ids": [
    "c4d7e6f3-2345-4bcd-aef0-123456789abc"
  ],
  "industry_includes_ids": [
    "b3c6f5e2-1234-4abc-9def-0123456789ab"
  ],
  "job_titles_excludes": [
    "Intern"
  ],
  "job_titles_includes": [
    "Head of Sales"
  ],
  "keywords": "AI sales",
  "last_name": "Alderson",
  "next_cursor": "<string>",
  "persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
  "prompt": "Head of Sales at AI startups in France",
  "recently_changed_jobs": true,
  "seniority_excludes": [
    "<string>"
  ],
  "seniority_includes": [
    "Director",
    "CXO"
  ],
  "years_of_experience": [
    "6 to 10 years"
  ]
}
'

import requests

url = "https://api.tamtam.ai/api/v2/people/search"

payload = {
    "canonical_job_titles_excludes_ids": ["<string>"],
    "canonical_job_titles_includes_ids": ["<string>"],
    "company_headcounts": ["C"],
    "company_hq_countries": ["FR"],
    "company_linkedin_ids": ["104924588"],
    "countries": ["FR"],
    "country_excludes": ["BE"],
    "cursor": "<string>",
    "first_name": "Elliot",
    "industry_excludes_ids": ["c4d7e6f3-2345-4bcd-aef0-123456789abc"],
    "industry_includes_ids": ["b3c6f5e2-1234-4abc-9def-0123456789ab"],
    "job_titles_excludes": ["Intern"],
    "job_titles_includes": ["Head of Sales"],
    "keywords": "AI sales",
    "last_name": "Alderson",
    "next_cursor": "<string>",
    "persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
    "prompt": "Head of Sales at AI startups in France",
    "recently_changed_jobs": True,
    "seniority_excludes": ["<string>"],
    "seniority_includes": ["Director", "CXO"],
    "years_of_experience": ["6 to 10 years"]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    canonical_job_titles_excludes_ids: ['<string>'],
    canonical_job_titles_includes_ids: ['<string>'],
    company_headcounts: ['C'],
    company_hq_countries: ['FR'],
    company_linkedin_ids: ['104924588'],
    countries: ['FR'],
    country_excludes: ['BE'],
    cursor: '<string>',
    first_name: 'Elliot',
    industry_excludes_ids: ['c4d7e6f3-2345-4bcd-aef0-123456789abc'],
    industry_includes_ids: ['b3c6f5e2-1234-4abc-9def-0123456789ab'],
    job_titles_excludes: ['Intern'],
    job_titles_includes: ['Head of Sales'],
    keywords: 'AI sales',
    last_name: 'Alderson',
    next_cursor: '<string>',
    persona_id: 'b3c6f5e2-1234-4abc-9def-0123456789ab',
    prompt: 'Head of Sales at AI startups in France',
    recently_changed_jobs: true,
    seniority_excludes: ['<string>'],
    seniority_includes: ['Director', 'CXO'],
    years_of_experience: ['6 to 10 years']
  })
};

fetch('https://api.tamtam.ai/api/v2/people/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tamtam.ai/api/v2/people/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'canonical_job_titles_excludes_ids' => [
        '<string>'
    ],
    'canonical_job_titles_includes_ids' => [
        '<string>'
    ],
    'company_headcounts' => [
        'C'
    ],
    'company_hq_countries' => [
        'FR'
    ],
    'company_linkedin_ids' => [
        '104924588'
    ],
    'countries' => [
        'FR'
    ],
    'country_excludes' => [
        'BE'
    ],
    'cursor' => '<string>',
    'first_name' => 'Elliot',
    'industry_excludes_ids' => [
        'c4d7e6f3-2345-4bcd-aef0-123456789abc'
    ],
    'industry_includes_ids' => [
        'b3c6f5e2-1234-4abc-9def-0123456789ab'
    ],
    'job_titles_excludes' => [
        'Intern'
    ],
    'job_titles_includes' => [
        'Head of Sales'
    ],
    'keywords' => 'AI sales',
    'last_name' => 'Alderson',
    'next_cursor' => '<string>',
    'persona_id' => 'b3c6f5e2-1234-4abc-9def-0123456789ab',
    'prompt' => 'Head of Sales at AI startups in France',
    'recently_changed_jobs' => true,
    'seniority_excludes' => [
        '<string>'
    ],
    'seniority_includes' => [
        'Director',
        'CXO'
    ],
    'years_of_experience' => [
        '6 to 10 years'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tamtam.ai/api/v2/people/search"

	payload := strings.NewReader("{\n  \"canonical_job_titles_excludes_ids\": [\n    \"<string>\"\n  ],\n  \"canonical_job_titles_includes_ids\": [\n    \"<string>\"\n  ],\n  \"company_headcounts\": [\n    \"C\"\n  ],\n  \"company_hq_countries\": [\n    \"FR\"\n  ],\n  \"company_linkedin_ids\": [\n    \"104924588\"\n  ],\n  \"countries\": [\n    \"FR\"\n  ],\n  \"country_excludes\": [\n    \"BE\"\n  ],\n  \"cursor\": \"<string>\",\n  \"first_name\": \"Elliot\",\n  \"industry_excludes_ids\": [\n    \"c4d7e6f3-2345-4bcd-aef0-123456789abc\"\n  ],\n  \"industry_includes_ids\": [\n    \"b3c6f5e2-1234-4abc-9def-0123456789ab\"\n  ],\n  \"job_titles_excludes\": [\n    \"Intern\"\n  ],\n  \"job_titles_includes\": [\n    \"Head of Sales\"\n  ],\n  \"keywords\": \"AI sales\",\n  \"last_name\": \"Alderson\",\n  \"next_cursor\": \"<string>\",\n  \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n  \"prompt\": \"Head of Sales at AI startups in France\",\n  \"recently_changed_jobs\": true,\n  \"seniority_excludes\": [\n    \"<string>\"\n  ],\n  \"seniority_includes\": [\n    \"Director\",\n    \"CXO\"\n  ],\n  \"years_of_experience\": [\n    \"6 to 10 years\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tamtam.ai/api/v2/people/search")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"canonical_job_titles_excludes_ids\": [\n    \"<string>\"\n  ],\n  \"canonical_job_titles_includes_ids\": [\n    \"<string>\"\n  ],\n  \"company_headcounts\": [\n    \"C\"\n  ],\n  \"company_hq_countries\": [\n    \"FR\"\n  ],\n  \"company_linkedin_ids\": [\n    \"104924588\"\n  ],\n  \"countries\": [\n    \"FR\"\n  ],\n  \"country_excludes\": [\n    \"BE\"\n  ],\n  \"cursor\": \"<string>\",\n  \"first_name\": \"Elliot\",\n  \"industry_excludes_ids\": [\n    \"c4d7e6f3-2345-4bcd-aef0-123456789abc\"\n  ],\n  \"industry_includes_ids\": [\n    \"b3c6f5e2-1234-4abc-9def-0123456789ab\"\n  ],\n  \"job_titles_excludes\": [\n    \"Intern\"\n  ],\n  \"job_titles_includes\": [\n    \"Head of Sales\"\n  ],\n  \"keywords\": \"AI sales\",\n  \"last_name\": \"Alderson\",\n  \"next_cursor\": \"<string>\",\n  \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n  \"prompt\": \"Head of Sales at AI startups in France\",\n  \"recently_changed_jobs\": true,\n  \"seniority_excludes\": [\n    \"<string>\"\n  ],\n  \"seniority_includes\": [\n    \"Director\",\n    \"CXO\"\n  ],\n  \"years_of_experience\": [\n    \"6 to 10 years\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tamtam.ai/api/v2/people/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"canonical_job_titles_excludes_ids\": [\n    \"<string>\"\n  ],\n  \"canonical_job_titles_includes_ids\": [\n    \"<string>\"\n  ],\n  \"company_headcounts\": [\n    \"C\"\n  ],\n  \"company_hq_countries\": [\n    \"FR\"\n  ],\n  \"company_linkedin_ids\": [\n    \"104924588\"\n  ],\n  \"countries\": [\n    \"FR\"\n  ],\n  \"country_excludes\": [\n    \"BE\"\n  ],\n  \"cursor\": \"<string>\",\n  \"first_name\": \"Elliot\",\n  \"industry_excludes_ids\": [\n    \"c4d7e6f3-2345-4bcd-aef0-123456789abc\"\n  ],\n  \"industry_includes_ids\": [\n    \"b3c6f5e2-1234-4abc-9def-0123456789ab\"\n  ],\n  \"job_titles_excludes\": [\n    \"Intern\"\n  ],\n  \"job_titles_includes\": [\n    \"Head of Sales\"\n  ],\n  \"keywords\": \"AI sales\",\n  \"last_name\": \"Alderson\",\n  \"next_cursor\": \"<string>\",\n  \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n  \"prompt\": \"Head of Sales at AI startups in France\",\n  \"recently_changed_jobs\": true,\n  \"seniority_excludes\": [\n    \"<string>\"\n  ],\n  \"seniority_includes\": [\n    \"Director\",\n    \"CXO\"\n  ],\n  \"years_of_experience\": [\n    \"6 to 10 years\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "dropped_by_seniority": 7,
  "has_more": true,
  "results": [
    {
      "contact_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
      "first_name": "Elliot",
      "job_title": "Head of Sales",
      "last_name": "Alderson",
      "linkedin_profile_id": "elliot-alderson",
      "profile_url": "https://www.linkedin.com/in/elliot-alderson",
      "seniorities": [
        "Director"
      ],
      "company_linkedin_id": "104924588",
      "company_logo_url": "https://media.licdn.com/dms/image/tamtam.png",
      "company_name": "TAMTAM",
      "location": "Paris, France",
      "profile_image_url": "https://media.licdn.com/dms/image/elliot.png",
      "summary": "Head of Sales at TAMTAM"
    }
  ],
  "cursor": "<string>",
  "filter_reasoning": "Interpreted as Head of Sales, country FR",
  "next_cursor": "<string>",
  "total_count": 132
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

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": [
    "C"
  ],
  "company_hq_countries": [
    "FR"
  ],
  "company_linkedin_ids": [
    "104924588"
  ],
  "countries": [
    "FR"
  ],
  "country_excludes": [
    "BE"
  ],
  "cursor": "<string>",
  "first_name": "Elliot",
  "industry_excludes_ids": [
    "c4d7e6f3-2345-4bcd-aef0-123456789abc"
  ],
  "industry_includes_ids": [
    "b3c6f5e2-1234-4abc-9def-0123456789ab"
  ],
  "job_titles_excludes": [
    "Intern"
  ],
  "job_titles_includes": [
    "Head of Sales"
  ],
  "keywords": "AI sales",
  "last_name": "Alderson",
  "next_cursor": "<string>",
  "persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
  "prompt": "Head of Sales at AI startups in France",
  "recently_changed_jobs": true,
  "seniority_excludes": [
    "<string>"
  ],
  "seniority_includes": [
    "Director",
    "CXO"
  ],
  "years_of_experience": [
    "6 to 10 years"
  ]
}
'

import requests

url = "https://api.tamtam.ai/api/v2/people/search"

payload = {
    "canonical_job_titles_excludes_ids": ["<string>"],
    "canonical_job_titles_includes_ids": ["<string>"],
    "company_headcounts": ["C"],
    "company_hq_countries": ["FR"],
    "company_linkedin_ids": ["104924588"],
    "countries": ["FR"],
    "country_excludes": ["BE"],
    "cursor": "<string>",
    "first_name": "Elliot",
    "industry_excludes_ids": ["c4d7e6f3-2345-4bcd-aef0-123456789abc"],
    "industry_includes_ids": ["b3c6f5e2-1234-4abc-9def-0123456789ab"],
    "job_titles_excludes": ["Intern"],
    "job_titles_includes": ["Head of Sales"],
    "keywords": "AI sales",
    "last_name": "Alderson",
    "next_cursor": "<string>",
    "persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
    "prompt": "Head of Sales at AI startups in France",
    "recently_changed_jobs": True,
    "seniority_excludes": ["<string>"],
    "seniority_includes": ["Director", "CXO"],
    "years_of_experience": ["6 to 10 years"]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    canonical_job_titles_excludes_ids: ['<string>'],
    canonical_job_titles_includes_ids: ['<string>'],
    company_headcounts: ['C'],
    company_hq_countries: ['FR'],
    company_linkedin_ids: ['104924588'],
    countries: ['FR'],
    country_excludes: ['BE'],
    cursor: '<string>',
    first_name: 'Elliot',
    industry_excludes_ids: ['c4d7e6f3-2345-4bcd-aef0-123456789abc'],
    industry_includes_ids: ['b3c6f5e2-1234-4abc-9def-0123456789ab'],
    job_titles_excludes: ['Intern'],
    job_titles_includes: ['Head of Sales'],
    keywords: 'AI sales',
    last_name: 'Alderson',
    next_cursor: '<string>',
    persona_id: 'b3c6f5e2-1234-4abc-9def-0123456789ab',
    prompt: 'Head of Sales at AI startups in France',
    recently_changed_jobs: true,
    seniority_excludes: ['<string>'],
    seniority_includes: ['Director', 'CXO'],
    years_of_experience: ['6 to 10 years']
  })
};

fetch('https://api.tamtam.ai/api/v2/people/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tamtam.ai/api/v2/people/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'canonical_job_titles_excludes_ids' => [
        '<string>'
    ],
    'canonical_job_titles_includes_ids' => [
        '<string>'
    ],
    'company_headcounts' => [
        'C'
    ],
    'company_hq_countries' => [
        'FR'
    ],
    'company_linkedin_ids' => [
        '104924588'
    ],
    'countries' => [
        'FR'
    ],
    'country_excludes' => [
        'BE'
    ],
    'cursor' => '<string>',
    'first_name' => 'Elliot',
    'industry_excludes_ids' => [
        'c4d7e6f3-2345-4bcd-aef0-123456789abc'
    ],
    'industry_includes_ids' => [
        'b3c6f5e2-1234-4abc-9def-0123456789ab'
    ],
    'job_titles_excludes' => [
        'Intern'
    ],
    'job_titles_includes' => [
        'Head of Sales'
    ],
    'keywords' => 'AI sales',
    'last_name' => 'Alderson',
    'next_cursor' => '<string>',
    'persona_id' => 'b3c6f5e2-1234-4abc-9def-0123456789ab',
    'prompt' => 'Head of Sales at AI startups in France',
    'recently_changed_jobs' => true,
    'seniority_excludes' => [
        '<string>'
    ],
    'seniority_includes' => [
        'Director',
        'CXO'
    ],
    'years_of_experience' => [
        '6 to 10 years'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tamtam.ai/api/v2/people/search"

	payload := strings.NewReader("{\n  \"canonical_job_titles_excludes_ids\": [\n    \"<string>\"\n  ],\n  \"canonical_job_titles_includes_ids\": [\n    \"<string>\"\n  ],\n  \"company_headcounts\": [\n    \"C\"\n  ],\n  \"company_hq_countries\": [\n    \"FR\"\n  ],\n  \"company_linkedin_ids\": [\n    \"104924588\"\n  ],\n  \"countries\": [\n    \"FR\"\n  ],\n  \"country_excludes\": [\n    \"BE\"\n  ],\n  \"cursor\": \"<string>\",\n  \"first_name\": \"Elliot\",\n  \"industry_excludes_ids\": [\n    \"c4d7e6f3-2345-4bcd-aef0-123456789abc\"\n  ],\n  \"industry_includes_ids\": [\n    \"b3c6f5e2-1234-4abc-9def-0123456789ab\"\n  ],\n  \"job_titles_excludes\": [\n    \"Intern\"\n  ],\n  \"job_titles_includes\": [\n    \"Head of Sales\"\n  ],\n  \"keywords\": \"AI sales\",\n  \"last_name\": \"Alderson\",\n  \"next_cursor\": \"<string>\",\n  \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n  \"prompt\": \"Head of Sales at AI startups in France\",\n  \"recently_changed_jobs\": true,\n  \"seniority_excludes\": [\n    \"<string>\"\n  ],\n  \"seniority_includes\": [\n    \"Director\",\n    \"CXO\"\n  ],\n  \"years_of_experience\": [\n    \"6 to 10 years\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tamtam.ai/api/v2/people/search")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"canonical_job_titles_excludes_ids\": [\n    \"<string>\"\n  ],\n  \"canonical_job_titles_includes_ids\": [\n    \"<string>\"\n  ],\n  \"company_headcounts\": [\n    \"C\"\n  ],\n  \"company_hq_countries\": [\n    \"FR\"\n  ],\n  \"company_linkedin_ids\": [\n    \"104924588\"\n  ],\n  \"countries\": [\n    \"FR\"\n  ],\n  \"country_excludes\": [\n    \"BE\"\n  ],\n  \"cursor\": \"<string>\",\n  \"first_name\": \"Elliot\",\n  \"industry_excludes_ids\": [\n    \"c4d7e6f3-2345-4bcd-aef0-123456789abc\"\n  ],\n  \"industry_includes_ids\": [\n    \"b3c6f5e2-1234-4abc-9def-0123456789ab\"\n  ],\n  \"job_titles_excludes\": [\n    \"Intern\"\n  ],\n  \"job_titles_includes\": [\n    \"Head of Sales\"\n  ],\n  \"keywords\": \"AI sales\",\n  \"last_name\": \"Alderson\",\n  \"next_cursor\": \"<string>\",\n  \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n  \"prompt\": \"Head of Sales at AI startups in France\",\n  \"recently_changed_jobs\": true,\n  \"seniority_excludes\": [\n    \"<string>\"\n  ],\n  \"seniority_includes\": [\n    \"Director\",\n    \"CXO\"\n  ],\n  \"years_of_experience\": [\n    \"6 to 10 years\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tamtam.ai/api/v2/people/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"canonical_job_titles_excludes_ids\": [\n    \"<string>\"\n  ],\n  \"canonical_job_titles_includes_ids\": [\n    \"<string>\"\n  ],\n  \"company_headcounts\": [\n    \"C\"\n  ],\n  \"company_hq_countries\": [\n    \"FR\"\n  ],\n  \"company_linkedin_ids\": [\n    \"104924588\"\n  ],\n  \"countries\": [\n    \"FR\"\n  ],\n  \"country_excludes\": [\n    \"BE\"\n  ],\n  \"cursor\": \"<string>\",\n  \"first_name\": \"Elliot\",\n  \"industry_excludes_ids\": [\n    \"c4d7e6f3-2345-4bcd-aef0-123456789abc\"\n  ],\n  \"industry_includes_ids\": [\n    \"b3c6f5e2-1234-4abc-9def-0123456789ab\"\n  ],\n  \"job_titles_excludes\": [\n    \"Intern\"\n  ],\n  \"job_titles_includes\": [\n    \"Head of Sales\"\n  ],\n  \"keywords\": \"AI sales\",\n  \"last_name\": \"Alderson\",\n  \"next_cursor\": \"<string>\",\n  \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n  \"prompt\": \"Head of Sales at AI startups in France\",\n  \"recently_changed_jobs\": true,\n  \"seniority_excludes\": [\n    \"<string>\"\n  ],\n  \"seniority_includes\": [\n    \"Director\",\n    \"CXO\"\n  ],\n  \"years_of_experience\": [\n    \"6 to 10 years\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "dropped_by_seniority": 7,
  "has_more": true,
  "results": [
    {
      "contact_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
      "first_name": "Elliot",
      "job_title": "Head of Sales",
      "last_name": "Alderson",
      "linkedin_profile_id": "elliot-alderson",
      "profile_url": "https://www.linkedin.com/in/elliot-alderson",
      "seniorities": [
        "Director"
      ],
      "company_linkedin_id": "104924588",
      "company_logo_url": "https://media.licdn.com/dms/image/tamtam.png",
      "company_name": "TAMTAM",
      "location": "Paris, France",
      "profile_image_url": "https://media.licdn.com/dms/image/elliot.png",
      "summary": "Head of Sales at TAMTAM"
    }
  ],
  "cursor": "<string>",
  "filter_reasoning": "Interpreted as Head of Sales, country FR",
  "next_cursor": "<string>",
  "total_count": 132
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

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

country_excludes

string[] | null

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

Example:

["BE"]

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.

persona_id

string

Search using one of your saved personas, which supplies the job titles, countries and seniority bands behind it. List them via Get 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"

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 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:

["Director", "CXO"]

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

dropped_by_seniority

integer<int64>

required

How many people this page's seniority_includes filter removed. Always 0 when seniority_includes is not sent.

Example:

7

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

Contacts

Workflow Runs

Companies Lists

Companies

Contacts Lists

Signals

Credits

Engagement Watches

ICP Criteria

ICP Signal Watches

Industries

Key Accounts

Lookalikes

People Enrichment

People Extract

People Search

Personas

Smart Verticals

Webhooks

Search for people

Authorizations

Body

Response