Preview a contact search
curl --request POST \
--url https://api.tamtam.ai/api/v2/contact-searches/preview-count \
--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"
]
}
]
}
'import requests
url = "https://api.tamtam.ai/api/v2/contact-searches/preview-count"
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"]
}
]
}
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']
}
]
})
};
fetch('https://api.tamtam.ai/api/v2/contact-searches/preview-count', 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/preview-count",
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'
]
]
]
]),
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/preview-count"
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}")
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/preview-count")
.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}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tamtam.ai/api/v2/contact-searches/preview-count")
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}"
response = http.request(request)
puts response.read_body{
"queries_counted": 123,
"queries_requested": 123,
"seniority_bands_ignored": [
"<string>"
],
"total": 412
}{
"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
Preview a contact search
How many people a contact search would match, before you start it. Takes the same companies and queries as Start a contact search.
Read it as a ceiling, not a forecast. It sums one count per query, so anyone matching two queries is counted twice; and it cannot apply seniority bands, which are read from a job title only after a profile has been fetched — seniority_bands_ignored names the ones it had to skip. The one direction it comes out too small is queries_counted below queries_requested, which caps what a single preview may spend: the queries left out contribute nobody to the total.
Costs no credits, but it is not instant: each query is a live provider count, a few seconds. Size an uncertain search with it — but do not preview what you are not about to run. It is refused with 402 when the account has no credits at all, since the search it sizes could not be started either.
POST
/
v2
/
contact-searches
/
preview-count
Preview a contact search
curl --request POST \
--url https://api.tamtam.ai/api/v2/contact-searches/preview-count \
--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"
]
}
]
}
'import requests
url = "https://api.tamtam.ai/api/v2/contact-searches/preview-count"
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"]
}
]
}
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']
}
]
})
};
fetch('https://api.tamtam.ai/api/v2/contact-searches/preview-count', 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/preview-count",
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'
]
]
]
]),
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/preview-count"
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}")
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/preview-count")
.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}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tamtam.ai/api/v2/contact-searches/preview-count")
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}"
response = http.request(request)
puts response.read_body{
"queries_counted": 123,
"queries_requested": 123,
"seniority_bands_ignored": [
"<string>"
],
"total": 412
}{
"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
The companies the search would run at.
Minimum array length:
1Example:
["104924588"]
The queries the search would run. Send the same ones you will submit: a count run without a filter you intend to search with sizes a different search.
Minimum array length:
1Show child attributes
Show child attributes
Response
OK
How many of the queries the count actually ran. Below queries_requested means total covers only the first N and is a FLOOR for the whole search rather than an estimate of it.
How many queries were sent.
Seniority bands the count could not apply, because seniority is read from a job title after a profile is fetched and never reaches a provider. Non-empty means total is an upper bound: the search will keep fewer people than this.
How many people the queries match across the companies, summed over queries. An upper bound on what the search would extract, never a forecast: it double-counts anyone matching two queries, and it cannot apply seniority bands (see seniority_bands_ignored).
Example:
412