Find prospects
curl --request POST \
--url https://api.example.com/v1/solutions/gtm/people_search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'idempotency-key: <idempotency-key>' \
--data '
{
"job_titles": [
"<string>"
],
"seniorities": [],
"locations": [
"<string>"
],
"company_domain": "<string>",
"keywords": "<string>",
"full_name": "<string>",
"email": "<string>",
"linkedin_url": "<string>",
"limit": 50
}
'import requests
url = "https://api.example.com/v1/solutions/gtm/people_search"
payload = {
"job_titles": ["<string>"],
"seniorities": [],
"locations": ["<string>"],
"company_domain": "<string>",
"keywords": "<string>",
"full_name": "<string>",
"email": "<string>",
"linkedin_url": "<string>",
"limit": 50
}
headers = {
"idempotency-key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'idempotency-key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
job_titles: ['<string>'],
seniorities: [],
locations: ['<string>'],
company_domain: '<string>',
keywords: '<string>',
full_name: '<string>',
email: '<string>',
linkedin_url: '<string>',
limit: 50
})
};
fetch('https://api.example.com/v1/solutions/gtm/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.example.com/v1/solutions/gtm/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([
'job_titles' => [
'<string>'
],
'seniorities' => [
],
'locations' => [
'<string>'
],
'company_domain' => '<string>',
'keywords' => '<string>',
'full_name' => '<string>',
'email' => '<string>',
'linkedin_url' => '<string>',
'limit' => 50
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"idempotency-key: <idempotency-key>"
],
]);
$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.example.com/v1/solutions/gtm/people_search"
payload := strings.NewReader("{\n \"job_titles\": [\n \"<string>\"\n ],\n \"seniorities\": [],\n \"locations\": [\n \"<string>\"\n ],\n \"company_domain\": \"<string>\",\n \"keywords\": \"<string>\",\n \"full_name\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"limit\": 50\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("idempotency-key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
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.example.com/v1/solutions/gtm/people_search")
.header("idempotency-key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"job_titles\": [\n \"<string>\"\n ],\n \"seniorities\": [],\n \"locations\": [\n \"<string>\"\n ],\n \"company_domain\": \"<string>\",\n \"keywords\": \"<string>\",\n \"full_name\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"limit\": 50\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/solutions/gtm/people_search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"job_titles\": [\n \"<string>\"\n ],\n \"seniorities\": [],\n \"locations\": [\n \"<string>\"\n ],\n \"company_domain\": \"<string>\",\n \"keywords\": \"<string>\",\n \"full_name\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"limit\": 50\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"run_url": "<string>",
"provider": "<string>",
"endpoint": "<string>",
"endpoint_version": 123,
"status": "QUEUED",
"failure": {
"kind": "TIMED_OUT",
"message": "<string>"
},
"input": {},
"output": "<unknown>",
"provider_response": {
"http_status": 349,
"error": null
},
"charge_usd": "<string>",
"charge_basis": {
"clause": "rule",
"quantity": 1
},
"stoppable": true,
"stop_requested_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"id": "<string>",
"run_url": "<string>",
"provider": "<string>",
"endpoint": "<string>",
"endpoint_version": 123,
"status": "QUEUED",
"failure": {
"kind": "TIMED_OUT",
"message": "<string>"
},
"input": {},
"output": "<unknown>",
"provider_response": {
"http_status": 349,
"error": null
},
"charge_usd": "<string>",
"charge_basis": {
"clause": "rule",
"quantity": 1
},
"stoppable": true,
"stop_requested_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "insufficient_balance",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "endpoint_not_permitted",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "idempotency_conflict",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "rate_limited",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "service_unavailable",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}Solutions
Find prospects
Find contacts by title, seniority, location or employer, enrich one person’s profile, or find a work email. Providers: Apollo, People Data Labs, LeadMagic, ZoomInfo, Hunter, Prospeo. Routes to one Endpoint per action; provider auto picks the first preferred Provider this key may run, a named provider forces it. The response is exactly the Run that POST /v1/runs returns — provider-native output, exact charge_usd, run_url; its provider, endpoint and input say which Endpoint served the call. Under auto, a Provider error, timeout or rate limit falls back to the next preferred Provider; a no-result answer does not. Each fallback hop is its own Run, visible in the runs list. Idempotency-Key is required and behaves exactly as on POST /v1/runs.
POST
/
v1
/
solutions
/
gtm
/
people_search
Find prospects
curl --request POST \
--url https://api.example.com/v1/solutions/gtm/people_search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'idempotency-key: <idempotency-key>' \
--data '
{
"job_titles": [
"<string>"
],
"seniorities": [],
"locations": [
"<string>"
],
"company_domain": "<string>",
"keywords": "<string>",
"full_name": "<string>",
"email": "<string>",
"linkedin_url": "<string>",
"limit": 50
}
'import requests
url = "https://api.example.com/v1/solutions/gtm/people_search"
payload = {
"job_titles": ["<string>"],
"seniorities": [],
"locations": ["<string>"],
"company_domain": "<string>",
"keywords": "<string>",
"full_name": "<string>",
"email": "<string>",
"linkedin_url": "<string>",
"limit": 50
}
headers = {
"idempotency-key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'idempotency-key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
job_titles: ['<string>'],
seniorities: [],
locations: ['<string>'],
company_domain: '<string>',
keywords: '<string>',
full_name: '<string>',
email: '<string>',
linkedin_url: '<string>',
limit: 50
})
};
fetch('https://api.example.com/v1/solutions/gtm/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.example.com/v1/solutions/gtm/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([
'job_titles' => [
'<string>'
],
'seniorities' => [
],
'locations' => [
'<string>'
],
'company_domain' => '<string>',
'keywords' => '<string>',
'full_name' => '<string>',
'email' => '<string>',
'linkedin_url' => '<string>',
'limit' => 50
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"idempotency-key: <idempotency-key>"
],
]);
$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.example.com/v1/solutions/gtm/people_search"
payload := strings.NewReader("{\n \"job_titles\": [\n \"<string>\"\n ],\n \"seniorities\": [],\n \"locations\": [\n \"<string>\"\n ],\n \"company_domain\": \"<string>\",\n \"keywords\": \"<string>\",\n \"full_name\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"limit\": 50\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("idempotency-key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
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.example.com/v1/solutions/gtm/people_search")
.header("idempotency-key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"job_titles\": [\n \"<string>\"\n ],\n \"seniorities\": [],\n \"locations\": [\n \"<string>\"\n ],\n \"company_domain\": \"<string>\",\n \"keywords\": \"<string>\",\n \"full_name\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"limit\": 50\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/solutions/gtm/people_search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"job_titles\": [\n \"<string>\"\n ],\n \"seniorities\": [],\n \"locations\": [\n \"<string>\"\n ],\n \"company_domain\": \"<string>\",\n \"keywords\": \"<string>\",\n \"full_name\": \"<string>\",\n \"email\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"limit\": 50\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"run_url": "<string>",
"provider": "<string>",
"endpoint": "<string>",
"endpoint_version": 123,
"status": "QUEUED",
"failure": {
"kind": "TIMED_OUT",
"message": "<string>"
},
"input": {},
"output": "<unknown>",
"provider_response": {
"http_status": 349,
"error": null
},
"charge_usd": "<string>",
"charge_basis": {
"clause": "rule",
"quantity": 1
},
"stoppable": true,
"stop_requested_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"id": "<string>",
"run_url": "<string>",
"provider": "<string>",
"endpoint": "<string>",
"endpoint_version": 123,
"status": "QUEUED",
"failure": {
"kind": "TIMED_OUT",
"message": "<string>"
},
"input": {},
"output": "<unknown>",
"provider_response": {
"http_status": 349,
"error": null
},
"charge_usd": "<string>",
"charge_basis": {
"clause": "rule",
"quantity": 1
},
"stoppable": true,
"stop_requested_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "insufficient_balance",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "endpoint_not_permitted",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "idempotency_conflict",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "rate_limited",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "service_unavailable",
"message": "<string>",
"reason": "<string>",
"control": "<string>",
"retry_after_ms": 123,
"details": {}
},
"request_id": "<string>"
}Headers
A caller-generated idempotency key (a UUID is recommended). One key binds to one run: a retry with the same key after a network timeout is a read, not a second execution.
Minimum string length:
1Body
application/json
Default search. search: people matching job_titles, seniorities, locations, company_domain or keywords (at least one); a filter is never silently dropped — under auto a Provider that cannot apply one of the given filters is skipped, a named Provider that cannot is refused with 400. enrich: one person from linkedin_url, email, or full_name plus company_domain. find_email: the work email of full_name at company_domain.
Available options:
search, enrich, find_email Data provider: auto (default) or one of apollo, pdl, leadmagic, zoominfo, hunter, prospeo. Name one only when the caller asks for that vendor.
Available options:
auto, apollo, pdl, leadmagic, zoominfo, hunter, prospeo Required array length:
1 - 20 elementsRequired string length:
1 - 200Seniority levels, one or more of owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern.
Required array length:
1 - 11 elementsAvailable options:
owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern Required array length:
1 - 20 elementsRequired string length:
1 - 200A website domain such as stripe.com. A full URL is accepted and reduced to its host.
Required string length:
3 - 253Required string length:
1 - 300Required string length:
1 - 200An email address.
Maximum string length:
320Pattern:
^[^\s@]+@[^\s@]+\.[^\s@]+$The person's LinkedIn profile URL, linkedin.com/in/. Not a company page.
Maximum string length:
2048Pattern:
linkedin\.com\/in\/[^/?#\s]+Rows to return. Keep it small: the routed Endpoint's charge rule may read it. Each capability caps it further.
Required range:
1 <= x <= 100Response
a terminal run: COMPLETED, FAILED or STOPPED
Pattern:
^[a-z0-9][a-z0-9-]*$Pattern:
^\/.+$Available options:
QUEUED, RUNNING, COMPLETED, FAILED, STOPPED Show child attributes
Show child attributes
Show child attributes
Show child attributes
Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats.
Pattern:
^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$Show child attributes
Show child attributes
ISO-8601 UTC timestamp
ISO-8601 UTC timestamp
ISO-8601 UTC timestamp
ISO-8601 UTC timestamp