Profiles - Search

Search BuyerCaddy’s people directory using free text and structured filters.
Use this endpoint to discover decision‑makers and candidates for outreach.
(Use Profiles — Purchase to unlock full contact details.)

Base URL: https://api.salescaddy.ai/api

Endpoint

POST /profiles/search

Headers

Authorization: Bearer <token> — required
X-On-Behalf-Of-User: [email protected] — required when export=true

Query parameters

Name	Type	Required	Default	Description
`export`	boolean	No	`false`	If `true`, returns a CSV file (stream) attributed to `X-On-Behalf-Of-User`.

Request body (JSON — trimmed illustration)

Commonly used fields (send only what you need):

{
  "query": "data platform",
  "titles": ["VP Data","Head of Data"],
  "seniority": ["Director","VP","C-Level"],
  "functions": ["Engineering","Data","IT"],
  "countries": ["US","DE","UK"],
  "companyDomains": ["hilton.com","marriott.com"],
  "industries": ["Hospitality","Travel"]
}

The Search response returns profile summaries (name, title, company, location, identifiers).
Use Profiles — Purchase to obtain emails/phones where available.

Example — Basic text search

curl -sS -X POST "https://api.salescaddy.ai/api/profiles/search?export=false"   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{ "query":"data platform" }'

const res = await fetch("https://api.salescaddy.ai/api/profiles/search?export=false", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TOKEN}`, "Content-Type":"application/json" },
  body: JSON.stringify({ query: "data platform" })
});
console.log(await res.json());

import os, requests, json
payload = { "query": "data platform" }
r = requests.post("https://api.salescaddy.ai/api/profiles/search",
                  params={"export":"false"},
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}", "Content-Type":"application/json"},
                  data=json.dumps(payload))
print(r.json())

using System.Text;
using System.Net.Http.Headers;
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", TOKEN);
var content = new StringContent("{"query":"data platform"}", Encoding.UTF8, "application/json");
var res = await http.PostAsync("https://api.salescaddy.ai/api/profiles/search?export=false", content);
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample JSON (trimmed):

{
  "totalPages": 54,
  "totalElements": 1067,
  "content": [
    {
      "id": "prof_001",
      "fullName": "Alex Johnson",
      "title": "VP Data Platform",
      "seniority": "VP",
      "function": "Data",
      "companyName": "Hilton",
      "companyDomain": "hilton.com",
      "country": "US",
      "city": "McLean",
      "linkedinUrl": "https://www.linkedin.com/in/alexjohnson/"
    },
    {
      "id": "prof_002",
      "fullName": "Maria Schmidt",
      "title": "Head of Data Engineering",
      "seniority": "Director",
      "function": "Engineering",
      "companyName": "Marriott International",
      "companyDomain": "marriott.com",
      "country": "DE",
      "city": "Frankfurt",
      "linkedinUrl": "https://www.linkedin.com/in/mariaschmidt/"
    }
  ]
}

Example — Filter by title & country

curl -sS -X POST "https://api.salescaddy.ai/api/profiles/search?export=false"   -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"   -d '{ "titles":["VP Data","Head of Data"], "countries":["US","DE"] }'

const url = "https://api.salescaddy.ai/api/profiles/search?export=false";
const body = { titles:["VP Data","Head of Data"], countries:["US","DE"] };
const res = await fetch(url, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TOKEN}`, "Content-Type":"application/json" },
  body: JSON.stringify(body)
});
console.log(await res.json());

payload = { "titles":["VP Data","Head of Data"], "countries":["US","DE"] }
r = requests.post("https://api.salescaddy.ai/api/profiles/search",
                  params={"export":"false"},
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}", "Content-Type":"application/json"},
                  json=payload)
print(r.json())

var payload = "{"titles":["VP Data","Head of Data"],"countries":["US","DE"]}";
var res = await http.PostAsync("https://api.salescaddy.ai/api/profiles/search?export=false",
                               new StringContent(payload, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());

Example — Filter by company domains

curl -sS -X POST "https://api.salescaddy.ai/api/profiles/search?export=false"   -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"   -d '{ "companyDomains":["hilton.com","marriott.com"], "functions":["Data","IT"] }'

const res = await fetch("https://api.salescaddy.ai/api/profiles/search?export=false", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TOKEN}`, "Content-Type":"application/json" },
  body: JSON.stringify({ companyDomains:["hilton.com","marriott.com"], functions:["Data","IT"] })
});
console.log(await res.json());

r = requests.post("https://api.salescaddy.ai/api/profiles/search",
                  params={"export":"false"},
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}", "Content-Type":"application/json"},
                  json={"companyDomains":["hilton.com","marriott.com"], "functions":["Data","IT"]})
print(r.json())

var payload = "{"companyDomains":["hilton.com","marriott.com"],"functions":["Data","IT"]}";
var res = await http.PostAsync("https://api.salescaddy.ai/api/profiles/search?export=false",
                               new StringContent(payload, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());

Example — CSV export (requires header)

curl -sS -X POST "https://api.salescaddy.ai/api/profiles/search?export=true"   -H "Authorization: Bearer $TOKEN"   -H "X-On-Behalf-Of-User: [email protected]"   -H "Content-Type: application/json"   -d '{ "query":"data platform", "countries":["US","DE"] }'   --output profiles_export.csv

const res = await fetch("https://api.salescaddy.ai/api/profiles/search?export=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKEN}`,
    "X-On-Behalf-Of-User": "[email protected]",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query:"data platform", countries:["US","DE"] })
});
const buf = await res.arrayBuffer(); /* save to file */

with requests.post("https://api.salescaddy.ai/api/profiles/search",
                   params={"export":"true"},
                   headers={
                     "Authorization": f"Bearer {os.environ['TOKEN']}",
                     "X-On-Behalf-Of-User":"[email protected]",
                     "Content-Type":"application/json"
                   },
                   json={"query":"data platform","countries":["US","DE"]},
                   stream=True) as r:
    r.raise_for_status()
    with open("profiles_export.csv","wb") as f:
        for chunk in r.iter_content(8192):
            if chunk: f.write(chunk)

http.DefaultRequestHeaders.Add("X-On-Behalf-Of-User","[email protected]");
var content = new StringContent("{"query":"data platform","countries":["US","DE"]}", Encoding.UTF8, "application/json");
var bytes = await (await http.PostAsync("https://api.salescaddy.ai/api/profiles/search?export=true", content)).Content.ReadAsByteArrayAsync();
System.IO.File.WriteAllBytes("profiles_export.csv", bytes);

CSV export is attributed to the provided user for billing/audit. The Search response (JSON) does not include purchased emails/phones — use Profiles — Purchase with ids from the result.

Errors

Code	Meaning	How to fix
400	Bad request	Validate body schema & types; include at least one meaningful filter (e.g., `query`).
401	Unauthorized	Provide/refresh token; add `Authorization: Bearer` header.
403	Forbidden	Client lacks permission for the resource or export.
404	Not found	No profiles matched the filters.
429	Rate limit exceeded	Retry with exponential backoff; respect `Retry-After` if present.
500	Internal server error	Retry later; contact support if persistent.