Companies - Search

Find companies by firmographic and stack signals.

Search for companies using free text and structured filters.
Supports pagination and optional CSV export.

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

---

Endpoint

POST /companies/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/export a file associated with X-On-Behalf-Of-User.

Request body (JSON — CompanySearchDTO, trimmed illustration)

Commonly used fields (send only what you need):

JSON

{
  "query": "hospitality",
  "countries": ["US","DE"],
  "industries": ["Hospitality","Travel"],
  "employeeRange": ["1001-5000","10001+"],
  "revenueRange": ["1B-10B","10B+"],
  "domains": ["hilton.com","marriott.com"]
}

Tip: You can combine free‑text query with filters. Omit fields you don’t use.

---

Example — Basic text search

Bash

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

Node

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

Python

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

C#

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

Sample JSON (trimmed):

JSON

{
  "totalPages": 12,
  "totalElements": 237,
  "content": [
    { "id":"comp_hilton", "domain":"hilton.com", "name":"Hilton", "employeeRange":"10001+", "industry":"Hospitality", "country":"US" },
    { "id":"comp_marriott", "domain":"marriott.com", "name":"Marriott International", "employeeRange":"10001+", "industry":"Hospitality", "country":"US" }
  ]
}

---

Example — Filters (country + employeeRange)

Bash

curl -sS -X POST "https://api.salescaddy.ai/api/companies/search?export=false"   -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"   -d '{ "query":"hotel", "countries":["US","DE"], "employeeRange":["1001-5000","10001+"] }'

Node

const url = "https://api.salescaddy.ai/api/companies/search?export=false";
const body = { query:"hotel", countries:["US","DE"], employeeRange:["1001-5000","10001+"] };
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());

Python

payload = { "query":"hotel", "countries":["US","DE"], "employeeRange":["1001-5000","10001+"] }
r = requests.post("https://api.salescaddy.ai/api/companies/search",
                  params={"export":"false"},
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}", "Content-Type":"application/json"},
                  json=payload)
print(r.json())

C#

var payload = "{"query":"hotel","countries":["US","DE"],"employeeRange":["1001-5000","10001+"]}";
var res = await http.PostAsync("https://api.salescaddy.ai/api/companies/search?export=false",
                               new StringContent(payload, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample JSON (trimmed):

JSON

{
  "totalPages": 5,
  "totalElements": 98,
  "content": [
    { "domain":"hyatt.com", "name":"Hyatt Hotels Corporation", "employeeRange":"5001-10000", "country":"US" },
    { "domain":"accor.com", "name":"Accor", "employeeRange":"10001+", "country":"FR" }
  ]
}

---

Example — CSV export (requires header)

Bash

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

Node

const res = await fetch("https://api.salescaddy.ai/api/companies/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:"hospitality", countries:["US","DE"] })
});
const buf = await res.arrayBuffer(); /* save to file */

Python

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

C#

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

When export=true, the API associates the export with the provided user and may bill accordingly. The response is CSV.

---

Example — Pagination

Bash

curl -sS -X POST "https://api.salescaddy.ai/api/companies/search?export=false&page=1&size=20"   -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"   -d '{ "query":"hospitality" }'

Node

const url = "https://api.salescaddy.ai/api/companies/search?export=false&page=1&size=20";
const res = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

r = requests.post("https://api.salescaddy.ai/api/companies/search",
                  params={"export":"false","page":1,"size":20},
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

var res = await http.PostAsync("https://api.salescaddy.ai/api/companies/search?export=false&page=1&size=20", null);
Console.WriteLine(await res.Content.ReadAsStringAsync());

---

Errors

Code	Meaning	How to fix
400	Bad request	Validate body schema & types (page/size integers).
401	Unauthorized	Provide/refresh token; add Authorization: Bearer header.
403	Forbidden	Client lacks permission for the resource or export.
404	Not found	No companies 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.

---