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": "\"supply chain\" AND SAP",
"last_name": "Alderson",
"next_cursor": "<string>",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"profile_languages": [
"en"
],
"prompt": "Head of Sales at AI startups in France",
"provider": "endor",
"recently_changed_jobs": true,
"seniority_excludes": [
"<string>"
],
"seniority_includes": [
"Director",
"CXO"
],
"use_persona_ai_extension": false,
"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": "\"supply chain\" AND SAP",
"last_name": "Alderson",
"next_cursor": "<string>",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"profile_languages": ["en"],
"prompt": "Head of Sales at AI startups in France",
"provider": "endor",
"recently_changed_jobs": True,
"seniority_excludes": ["<string>"],
"seniority_includes": ["Director", "CXO"],
"use_persona_ai_extension": False,
"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: '"supply chain" AND SAP',
last_name: 'Alderson',
next_cursor: '<string>',
persona_id: 'b3c6f5e2-1234-4abc-9def-0123456789ab',
profile_languages: ['en'],
prompt: 'Head of Sales at AI startups in France',
provider: 'endor',
recently_changed_jobs: true,
seniority_excludes: ['<string>'],
seniority_includes: ['Director', 'CXO'],
use_persona_ai_extension: false,
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' => '"supply chain" AND SAP',
'last_name' => 'Alderson',
'next_cursor' => '<string>',
'persona_id' => 'b3c6f5e2-1234-4abc-9def-0123456789ab',
'profile_languages' => [
'en'
],
'prompt' => 'Head of Sales at AI startups in France',
'provider' => 'endor',
'recently_changed_jobs' => true,
'seniority_excludes' => [
'<string>'
],
'seniority_includes' => [
'Director',
'CXO'
],
'use_persona_ai_extension' => false,
'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\": \"\\\"supply chain\\\" AND SAP\",\n \"last_name\": \"Alderson\",\n \"next_cursor\": \"<string>\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"profile_languages\": [\n \"en\"\n ],\n \"prompt\": \"Head of Sales at AI startups in France\",\n \"provider\": \"endor\",\n \"recently_changed_jobs\": true,\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ],\n \"use_persona_ai_extension\": false,\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\": \"\\\"supply chain\\\" AND SAP\",\n \"last_name\": \"Alderson\",\n \"next_cursor\": \"<string>\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"profile_languages\": [\n \"en\"\n ],\n \"prompt\": \"Head of Sales at AI startups in France\",\n \"provider\": \"endor\",\n \"recently_changed_jobs\": true,\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ],\n \"use_persona_ai_extension\": false,\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\": \"\\\"supply chain\\\" AND SAP\",\n \"last_name\": \"Alderson\",\n \"next_cursor\": \"<string>\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"profile_languages\": [\n \"en\"\n ],\n \"prompt\": \"Head of Sales at AI startups in France\",\n \"provider\": \"endor\",\n \"recently_changed_jobs\": true,\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ],\n \"use_persona_ai_extension\": false,\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",
"initials": "EA",
"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",
"job_title_breadth": 18,
"next_cursor": "<string>",
"pagination_warning": "This search's job-title filter is wide: 18 titles. ...",
"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"
}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.
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": "\"supply chain\" AND SAP",
"last_name": "Alderson",
"next_cursor": "<string>",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"profile_languages": [
"en"
],
"prompt": "Head of Sales at AI startups in France",
"provider": "endor",
"recently_changed_jobs": true,
"seniority_excludes": [
"<string>"
],
"seniority_includes": [
"Director",
"CXO"
],
"use_persona_ai_extension": false,
"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": "\"supply chain\" AND SAP",
"last_name": "Alderson",
"next_cursor": "<string>",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"profile_languages": ["en"],
"prompt": "Head of Sales at AI startups in France",
"provider": "endor",
"recently_changed_jobs": True,
"seniority_excludes": ["<string>"],
"seniority_includes": ["Director", "CXO"],
"use_persona_ai_extension": False,
"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: '"supply chain" AND SAP',
last_name: 'Alderson',
next_cursor: '<string>',
persona_id: 'b3c6f5e2-1234-4abc-9def-0123456789ab',
profile_languages: ['en'],
prompt: 'Head of Sales at AI startups in France',
provider: 'endor',
recently_changed_jobs: true,
seniority_excludes: ['<string>'],
seniority_includes: ['Director', 'CXO'],
use_persona_ai_extension: false,
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' => '"supply chain" AND SAP',
'last_name' => 'Alderson',
'next_cursor' => '<string>',
'persona_id' => 'b3c6f5e2-1234-4abc-9def-0123456789ab',
'profile_languages' => [
'en'
],
'prompt' => 'Head of Sales at AI startups in France',
'provider' => 'endor',
'recently_changed_jobs' => true,
'seniority_excludes' => [
'<string>'
],
'seniority_includes' => [
'Director',
'CXO'
],
'use_persona_ai_extension' => false,
'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\": \"\\\"supply chain\\\" AND SAP\",\n \"last_name\": \"Alderson\",\n \"next_cursor\": \"<string>\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"profile_languages\": [\n \"en\"\n ],\n \"prompt\": \"Head of Sales at AI startups in France\",\n \"provider\": \"endor\",\n \"recently_changed_jobs\": true,\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ],\n \"use_persona_ai_extension\": false,\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\": \"\\\"supply chain\\\" AND SAP\",\n \"last_name\": \"Alderson\",\n \"next_cursor\": \"<string>\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"profile_languages\": [\n \"en\"\n ],\n \"prompt\": \"Head of Sales at AI startups in France\",\n \"provider\": \"endor\",\n \"recently_changed_jobs\": true,\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ],\n \"use_persona_ai_extension\": false,\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\": \"\\\"supply chain\\\" AND SAP\",\n \"last_name\": \"Alderson\",\n \"next_cursor\": \"<string>\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"profile_languages\": [\n \"en\"\n ],\n \"prompt\": \"Head of Sales at AI startups in France\",\n \"provider\": \"endor\",\n \"recently_changed_jobs\": true,\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ],\n \"use_persona_ai_extension\": false,\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",
"initials": "EA",
"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",
"job_title_breadth": 18,
"next_cursor": "<string>",
"pagination_warning": "This search's job-title filter is wide: 18 titles. ...",
"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
Account API key passed in the Authorization header
Body
Canonical job title IDs to exclude
Canonical job title IDs to include
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+.
["C"]
Company HQ country codes
["FR"]
LinkedIn company IDs to filter by
["104924588"]
Country codes to filter by
["FR"]
Country codes to exclude. Narrows a search rather than describing one, so it cannot be the only filter sent.
["BE"]
Deprecated. Ignored by the server. Use next_cursor.
Filter by first name
"Elliot"
Industry IDs to exclude.
Resolve via Search industries and pass the returned id.
["c4d7e6f3-2345-4bcd-aef0-123456789abc"]
Industry IDs to include.
Resolve via Search industries and pass the returned id.
["b3c6f5e2-1234-4abc-9def-0123456789ab"]
Job titles to exclude
["Intern"]
Job titles to include
["Head of Sales"]
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.
"\"supply chain\" AND SAP"
Filter by last name
"Alderson"
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.
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.
"b3c6f5e2-1234-4abc-9def-0123456789ab"
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.
["en"]
Free-text search prompt (e.g. 'CTOs at fintech startups in France'). Mutually exclusive with filter fields.
"Head of Sales at AI startups in France"
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.
endor, bespin "endor"
Only include people who recently changed jobs
true
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 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.
["Director", "CXO"]
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.
false
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.
["6 to 10 years"]
Response
OK
How many people this page's seniority_includes filter removed. Always 0 when seniority_includes is not sent.
7
True when more pages can be fetched by passing next_cursor back.
Search results for this page (up to 25)
Show child attributes
Show child attributes
Deprecated. Mirrors next_cursor. Use next_cursor instead.
When Prompt is used, explains how the AI interpreted the prompt into filters. Returned on the first page only.
"Interpreted as Head of Sales, country FR"
How many job titles this search actually ran with, counted after a prompt was interpreted and a persona expanded. Present only when that facet is wide enough that paging the search deep returns people an earlier page already returned; absent otherwise, so its presence is the signal. Sent on every page it applies to.
18
Opaque pagination token. Pass it back unchanged to fetch the next page. Null when there are no more results.
Why paging this search deep costs you people, and how to split it instead. Present exactly when job_title_breadth is, on every page. Prose meant to be read, not matched on: treat its presence as the signal and do not parse it.
"This search's job-title filter is wide: 18 titles. ..."
Total number of matching results. Returned on the first page only.
132