Start a contact search
curl --request POST \
--url https://api.tamtam.ai/api/v2/contact-searches \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"company_linkedin_ids": [
"104924588"
],
"queries": [
{
"canonical_job_titles_excludes_ids": [
"<string>"
],
"canonical_job_titles_includes_ids": [
"<string>"
],
"countries": [
"FR"
],
"country_excludes": [
"BE"
],
"include_past_job_titles": false,
"job_titles_excludes": [
"Intern"
],
"job_titles_includes": [
"Head of Sales",
"VP Sales"
],
"keywords": "\"supply chain\" AND SAP",
"label": "Revenue leadership",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"seniority_excludes": [
"<string>"
],
"seniority_includes": [
"Director",
"CXO"
]
}
],
"destination_contacts_list_id": "<string>",
"enrich_emails": true,
"enrich_phones": true,
"idempotency_key": "<string>",
"low_lead_score_threshold": 40,
"max_profiles_per_company_persona": 20,
"user_email": "rep@acme.com"
}
'import requests
url = "https://api.tamtam.ai/api/v2/contact-searches"
payload = {
"company_linkedin_ids": ["104924588"],
"queries": [
{
"canonical_job_titles_excludes_ids": ["<string>"],
"canonical_job_titles_includes_ids": ["<string>"],
"countries": ["FR"],
"country_excludes": ["BE"],
"include_past_job_titles": False,
"job_titles_excludes": ["Intern"],
"job_titles_includes": ["Head of Sales", "VP Sales"],
"keywords": "\"supply chain\" AND SAP",
"label": "Revenue leadership",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"seniority_excludes": ["<string>"],
"seniority_includes": ["Director", "CXO"]
}
],
"destination_contacts_list_id": "<string>",
"enrich_emails": True,
"enrich_phones": True,
"idempotency_key": "<string>",
"low_lead_score_threshold": 40,
"max_profiles_per_company_persona": 20,
"user_email": "rep@acme.com"
}
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({
company_linkedin_ids: ['104924588'],
queries: [
{
canonical_job_titles_excludes_ids: ['<string>'],
canonical_job_titles_includes_ids: ['<string>'],
countries: ['FR'],
country_excludes: ['BE'],
include_past_job_titles: false,
job_titles_excludes: ['Intern'],
job_titles_includes: ['Head of Sales', 'VP Sales'],
keywords: '"supply chain" AND SAP',
label: 'Revenue leadership',
persona_id: 'b3c6f5e2-1234-4abc-9def-0123456789ab',
seniority_excludes: ['<string>'],
seniority_includes: ['Director', 'CXO']
}
],
destination_contacts_list_id: '<string>',
enrich_emails: true,
enrich_phones: true,
idempotency_key: '<string>',
low_lead_score_threshold: 40,
max_profiles_per_company_persona: 20,
user_email: 'rep@acme.com'
})
};
fetch('https://api.tamtam.ai/api/v2/contact-searches', 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/contact-searches",
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([
'company_linkedin_ids' => [
'104924588'
],
'queries' => [
[
'canonical_job_titles_excludes_ids' => [
'<string>'
],
'canonical_job_titles_includes_ids' => [
'<string>'
],
'countries' => [
'FR'
],
'country_excludes' => [
'BE'
],
'include_past_job_titles' => false,
'job_titles_excludes' => [
'Intern'
],
'job_titles_includes' => [
'Head of Sales',
'VP Sales'
],
'keywords' => '"supply chain" AND SAP',
'label' => 'Revenue leadership',
'persona_id' => 'b3c6f5e2-1234-4abc-9def-0123456789ab',
'seniority_excludes' => [
'<string>'
],
'seniority_includes' => [
'Director',
'CXO'
]
]
],
'destination_contacts_list_id' => '<string>',
'enrich_emails' => true,
'enrich_phones' => true,
'idempotency_key' => '<string>',
'low_lead_score_threshold' => 40,
'max_profiles_per_company_persona' => 20,
'user_email' => 'rep@acme.com'
]),
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/contact-searches"
payload := strings.NewReader("{\n \"company_linkedin_ids\": [\n \"104924588\"\n ],\n \"queries\": [\n {\n \"canonical_job_titles_excludes_ids\": [\n \"<string>\"\n ],\n \"canonical_job_titles_includes_ids\": [\n \"<string>\"\n ],\n \"countries\": [\n \"FR\"\n ],\n \"country_excludes\": [\n \"BE\"\n ],\n \"include_past_job_titles\": false,\n \"job_titles_excludes\": [\n \"Intern\"\n ],\n \"job_titles_includes\": [\n \"Head of Sales\",\n \"VP Sales\"\n ],\n \"keywords\": \"\\\"supply chain\\\" AND SAP\",\n \"label\": \"Revenue leadership\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ]\n }\n ],\n \"destination_contacts_list_id\": \"<string>\",\n \"enrich_emails\": true,\n \"enrich_phones\": true,\n \"idempotency_key\": \"<string>\",\n \"low_lead_score_threshold\": 40,\n \"max_profiles_per_company_persona\": 20,\n \"user_email\": \"rep@acme.com\"\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/contact-searches")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"company_linkedin_ids\": [\n \"104924588\"\n ],\n \"queries\": [\n {\n \"canonical_job_titles_excludes_ids\": [\n \"<string>\"\n ],\n \"canonical_job_titles_includes_ids\": [\n \"<string>\"\n ],\n \"countries\": [\n \"FR\"\n ],\n \"country_excludes\": [\n \"BE\"\n ],\n \"include_past_job_titles\": false,\n \"job_titles_excludes\": [\n \"Intern\"\n ],\n \"job_titles_includes\": [\n \"Head of Sales\",\n \"VP Sales\"\n ],\n \"keywords\": \"\\\"supply chain\\\" AND SAP\",\n \"label\": \"Revenue leadership\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ]\n }\n ],\n \"destination_contacts_list_id\": \"<string>\",\n \"enrich_emails\": true,\n \"enrich_phones\": true,\n \"idempotency_key\": \"<string>\",\n \"low_lead_score_threshold\": 40,\n \"max_profiles_per_company_persona\": 20,\n \"user_email\": \"rep@acme.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tamtam.ai/api/v2/contact-searches")
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 \"company_linkedin_ids\": [\n \"104924588\"\n ],\n \"queries\": [\n {\n \"canonical_job_titles_excludes_ids\": [\n \"<string>\"\n ],\n \"canonical_job_titles_includes_ids\": [\n \"<string>\"\n ],\n \"countries\": [\n \"FR\"\n ],\n \"country_excludes\": [\n \"BE\"\n ],\n \"include_past_job_titles\": false,\n \"job_titles_excludes\": [\n \"Intern\"\n ],\n \"job_titles_includes\": [\n \"Head of Sales\",\n \"VP Sales\"\n ],\n \"keywords\": \"\\\"supply chain\\\" AND SAP\",\n \"label\": \"Revenue leadership\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ]\n }\n ],\n \"destination_contacts_list_id\": \"<string>\",\n \"enrich_emails\": true,\n \"enrich_phones\": true,\n \"idempotency_key\": \"<string>\",\n \"low_lead_score_threshold\": 40,\n \"max_profiles_per_company_persona\": 20,\n \"user_email\": \"rep@acme.com\"\n}"
response = http.request(request)
puts response.read_body{
"company_linkedin_ids": [
"<string>"
],
"contacts_list_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by_user_email": "<string>",
"id": "<string>",
"name": "<string>",
"queries": [
{
"include_past_job_titles": true,
"label": "<string>",
"canonical_job_titles_excludes_ids": [
"<string>"
],
"canonical_job_titles_includes_ids": [
"<string>"
],
"countries": [
"<string>"
],
"country_excludes": [
"<string>"
],
"job_titles_excludes": [
"<string>"
],
"job_titles_includes": [
"<string>"
],
"keywords": "<string>",
"persona_id": "<string>",
"seniority_excludes": [
"<string>"
],
"seniority_includes": [
"<string>"
]
}
],
"status": {
"cancelled_jobs": 123,
"companies_searched": 123,
"contacts_in_list_count": 123,
"done_jobs": 123,
"phase": "Searching",
"skipped_deleted_company_jobs": 123,
"total_jobs": 123,
"total_processed_results": 123,
"empty_reason": "<string>"
},
"already_existed": true
}{
"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"
}Contact Searches
Start a contact search
Find everyone matching any of several personas at each of several companies, and collect them into one deduplicated contacts list.
This is the fan-out counterpart of Search for people. That operation answers “the next 25 people matching one filter set” and returns them to you; this one runs queries x company_linkedin_ids searches in the background, merges what they find, removes duplicates, and keeps the result as a list. Use it when you have a target account list and the personas you sell to, and want everyone rather than a page.
It returns as soon as the search has started, not when it has finished — a wide one runs for minutes to hours. Poll Get a contact search for status.phase, and read the people through List the contacts in a contacts list with the contacts_list_id below. Contacts appear there as they are found, so you can read the list while it fills.
Cost. 1 credit per profile extracted, plus enrichment where you asked for it. A pair that matches nobody costs nothing, so the price is not the fan-out size — size it first with Preview a contact search. The call is refused with 402 only when the account has no credits at all.
POST
/
v2
/
contact-searches
Start a contact search
curl --request POST \
--url https://api.tamtam.ai/api/v2/contact-searches \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"company_linkedin_ids": [
"104924588"
],
"queries": [
{
"canonical_job_titles_excludes_ids": [
"<string>"
],
"canonical_job_titles_includes_ids": [
"<string>"
],
"countries": [
"FR"
],
"country_excludes": [
"BE"
],
"include_past_job_titles": false,
"job_titles_excludes": [
"Intern"
],
"job_titles_includes": [
"Head of Sales",
"VP Sales"
],
"keywords": "\"supply chain\" AND SAP",
"label": "Revenue leadership",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"seniority_excludes": [
"<string>"
],
"seniority_includes": [
"Director",
"CXO"
]
}
],
"destination_contacts_list_id": "<string>",
"enrich_emails": true,
"enrich_phones": true,
"idempotency_key": "<string>",
"low_lead_score_threshold": 40,
"max_profiles_per_company_persona": 20,
"user_email": "rep@acme.com"
}
'import requests
url = "https://api.tamtam.ai/api/v2/contact-searches"
payload = {
"company_linkedin_ids": ["104924588"],
"queries": [
{
"canonical_job_titles_excludes_ids": ["<string>"],
"canonical_job_titles_includes_ids": ["<string>"],
"countries": ["FR"],
"country_excludes": ["BE"],
"include_past_job_titles": False,
"job_titles_excludes": ["Intern"],
"job_titles_includes": ["Head of Sales", "VP Sales"],
"keywords": "\"supply chain\" AND SAP",
"label": "Revenue leadership",
"persona_id": "b3c6f5e2-1234-4abc-9def-0123456789ab",
"seniority_excludes": ["<string>"],
"seniority_includes": ["Director", "CXO"]
}
],
"destination_contacts_list_id": "<string>",
"enrich_emails": True,
"enrich_phones": True,
"idempotency_key": "<string>",
"low_lead_score_threshold": 40,
"max_profiles_per_company_persona": 20,
"user_email": "rep@acme.com"
}
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({
company_linkedin_ids: ['104924588'],
queries: [
{
canonical_job_titles_excludes_ids: ['<string>'],
canonical_job_titles_includes_ids: ['<string>'],
countries: ['FR'],
country_excludes: ['BE'],
include_past_job_titles: false,
job_titles_excludes: ['Intern'],
job_titles_includes: ['Head of Sales', 'VP Sales'],
keywords: '"supply chain" AND SAP',
label: 'Revenue leadership',
persona_id: 'b3c6f5e2-1234-4abc-9def-0123456789ab',
seniority_excludes: ['<string>'],
seniority_includes: ['Director', 'CXO']
}
],
destination_contacts_list_id: '<string>',
enrich_emails: true,
enrich_phones: true,
idempotency_key: '<string>',
low_lead_score_threshold: 40,
max_profiles_per_company_persona: 20,
user_email: 'rep@acme.com'
})
};
fetch('https://api.tamtam.ai/api/v2/contact-searches', 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/contact-searches",
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([
'company_linkedin_ids' => [
'104924588'
],
'queries' => [
[
'canonical_job_titles_excludes_ids' => [
'<string>'
],
'canonical_job_titles_includes_ids' => [
'<string>'
],
'countries' => [
'FR'
],
'country_excludes' => [
'BE'
],
'include_past_job_titles' => false,
'job_titles_excludes' => [
'Intern'
],
'job_titles_includes' => [
'Head of Sales',
'VP Sales'
],
'keywords' => '"supply chain" AND SAP',
'label' => 'Revenue leadership',
'persona_id' => 'b3c6f5e2-1234-4abc-9def-0123456789ab',
'seniority_excludes' => [
'<string>'
],
'seniority_includes' => [
'Director',
'CXO'
]
]
],
'destination_contacts_list_id' => '<string>',
'enrich_emails' => true,
'enrich_phones' => true,
'idempotency_key' => '<string>',
'low_lead_score_threshold' => 40,
'max_profiles_per_company_persona' => 20,
'user_email' => 'rep@acme.com'
]),
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/contact-searches"
payload := strings.NewReader("{\n \"company_linkedin_ids\": [\n \"104924588\"\n ],\n \"queries\": [\n {\n \"canonical_job_titles_excludes_ids\": [\n \"<string>\"\n ],\n \"canonical_job_titles_includes_ids\": [\n \"<string>\"\n ],\n \"countries\": [\n \"FR\"\n ],\n \"country_excludes\": [\n \"BE\"\n ],\n \"include_past_job_titles\": false,\n \"job_titles_excludes\": [\n \"Intern\"\n ],\n \"job_titles_includes\": [\n \"Head of Sales\",\n \"VP Sales\"\n ],\n \"keywords\": \"\\\"supply chain\\\" AND SAP\",\n \"label\": \"Revenue leadership\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ]\n }\n ],\n \"destination_contacts_list_id\": \"<string>\",\n \"enrich_emails\": true,\n \"enrich_phones\": true,\n \"idempotency_key\": \"<string>\",\n \"low_lead_score_threshold\": 40,\n \"max_profiles_per_company_persona\": 20,\n \"user_email\": \"rep@acme.com\"\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/contact-searches")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"company_linkedin_ids\": [\n \"104924588\"\n ],\n \"queries\": [\n {\n \"canonical_job_titles_excludes_ids\": [\n \"<string>\"\n ],\n \"canonical_job_titles_includes_ids\": [\n \"<string>\"\n ],\n \"countries\": [\n \"FR\"\n ],\n \"country_excludes\": [\n \"BE\"\n ],\n \"include_past_job_titles\": false,\n \"job_titles_excludes\": [\n \"Intern\"\n ],\n \"job_titles_includes\": [\n \"Head of Sales\",\n \"VP Sales\"\n ],\n \"keywords\": \"\\\"supply chain\\\" AND SAP\",\n \"label\": \"Revenue leadership\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ]\n }\n ],\n \"destination_contacts_list_id\": \"<string>\",\n \"enrich_emails\": true,\n \"enrich_phones\": true,\n \"idempotency_key\": \"<string>\",\n \"low_lead_score_threshold\": 40,\n \"max_profiles_per_company_persona\": 20,\n \"user_email\": \"rep@acme.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tamtam.ai/api/v2/contact-searches")
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 \"company_linkedin_ids\": [\n \"104924588\"\n ],\n \"queries\": [\n {\n \"canonical_job_titles_excludes_ids\": [\n \"<string>\"\n ],\n \"canonical_job_titles_includes_ids\": [\n \"<string>\"\n ],\n \"countries\": [\n \"FR\"\n ],\n \"country_excludes\": [\n \"BE\"\n ],\n \"include_past_job_titles\": false,\n \"job_titles_excludes\": [\n \"Intern\"\n ],\n \"job_titles_includes\": [\n \"Head of Sales\",\n \"VP Sales\"\n ],\n \"keywords\": \"\\\"supply chain\\\" AND SAP\",\n \"label\": \"Revenue leadership\",\n \"persona_id\": \"b3c6f5e2-1234-4abc-9def-0123456789ab\",\n \"seniority_excludes\": [\n \"<string>\"\n ],\n \"seniority_includes\": [\n \"Director\",\n \"CXO\"\n ]\n }\n ],\n \"destination_contacts_list_id\": \"<string>\",\n \"enrich_emails\": true,\n \"enrich_phones\": true,\n \"idempotency_key\": \"<string>\",\n \"low_lead_score_threshold\": 40,\n \"max_profiles_per_company_persona\": 20,\n \"user_email\": \"rep@acme.com\"\n}"
response = http.request(request)
puts response.read_body{
"company_linkedin_ids": [
"<string>"
],
"contacts_list_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by_user_email": "<string>",
"id": "<string>",
"name": "<string>",
"queries": [
{
"include_past_job_titles": true,
"label": "<string>",
"canonical_job_titles_excludes_ids": [
"<string>"
],
"canonical_job_titles_includes_ids": [
"<string>"
],
"countries": [
"<string>"
],
"country_excludes": [
"<string>"
],
"job_titles_excludes": [
"<string>"
],
"job_titles_includes": [
"<string>"
],
"keywords": "<string>",
"persona_id": "<string>",
"seniority_excludes": [
"<string>"
],
"seniority_includes": [
"<string>"
]
}
],
"status": {
"cancelled_jobs": 123,
"companies_searched": 123,
"contacts_in_list_count": 123,
"done_jobs": 123,
"phase": "Searching",
"skipped_deleted_company_jobs": 123,
"total_jobs": 123,
"total_processed_results": 123,
"empty_reason": "<string>"
},
"already_existed": true
}{
"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
apikeyAuthbearerAuth
Account API key passed in the Authorization header
Body
application/json
LinkedIn company IDs to search, at least one. Every query runs at every company, so this multiplies the work: resolve them via Search for a company or read them off a companies list.
Minimum array length:
1Example:
["104924588"]
The personas to look for, at least one. Each runs at every company and the results are merged into one list, deduplicated, so a person matching two queries appears once.
Minimum array length:
1Show child attributes
Show child attributes
Deliver into a contacts list that already exists instead of creating one — 're-run into this list'. Any list you could add to by hand; a Tamtam-managed list is refused. Omitted, the search makes its own list and the account's standing list-building columns are attached to it, exactly as they would be in the app.
Also look up a professional email for each extracted contact. Charged per enrichment on top of the extraction, and only for contacts that clear low_lead_score_threshold.
Also look up a phone number for each extracted contact. Same charging and same lead-score cut as enrich_emails.
Your own key for this submission, so a retried POST returns the search the first one started instead of starting a second. Omitted, every call starts a new search — which is what a fresh request usually means.
A key is unique per account for good: reusing one more than 30 seconds later is a 409, not a replay.
Buy an email or a phone only for a contact whose Lead Score reaches this. Omitted, every extracted contact is enriched. Ignored when neither enrich_emails nor enrich_phones is set.
Example:
40
Cap on the profiles fetched for each (query, company) pair. Omitted, the search is exhaustive up to the platform maximum.
This is a cap, not a target: a pair that matches nobody costs nothing, and 1 credit is charged per profile actually extracted.
Example:
20
Who to attribute the search to in the app. Freeform and opaque to us; an API key authenticates the workspace, not a person, so nothing is inferred when this is omitted.
Example:
"rep@acme.com"
Response
Accepted
The contacts list this search delivers into. This is the id to read results with — List the contacts in a contacts list — and several searches may share one.
Whatever user_email the submission carried; empty when it carried none.
The SEARCH's id. Pass it to the status and stop operations.
Derived at submit time from the queries and companies, e.g. 'Revenue leadership @ Acme, Globex and 3 others'.
The queries as submitted, frozen. A persona edited since does not change them.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Only on a create: true when your idempotency_key matched a submission already in flight, so this is that search rather than a new one.