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 '{
  "page": 0,
  "size": 10,
  "filter": {
    "companyNameContains": "export",
    "vendorDomainInAnd": false,
    "vendorDomainNotInAnd": false,
    "productIdInAnd": false,
    "productIdNotInAnd": false,
    "mainCategoryIdInAnd": false,
    "mainCategoryIdNotInAnd": false,
    "intensityBucketIn": [
      "LOW"
    ],
    "dateLastVerifiedBucketIn": [
      "ANCIENT"
    ]
  }
}'

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": 2138,
  "totalElements": 21380,
  "content": [
    {
      "id": "A079E6EA39E6932C2F26A6A13906878D",
      "domain": "aurosethi.de",
      "name": "\"AUROSETHI\" IMPORT EXPORT GmbH",
      "logo": "https://img.logo.dev/aurosethi.de?token=pk_S-z4OHSVRdqZEzd20vlKcw",
      "industry": "Groceries and related products",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "city": "Frankfurt am Main",
      "state": "Hessen",
      "country": "Germany"
    },
    {
      "id": "D866C3EA9C2D77A2C22D3CB201FCE862",
      "domain": "auto-lardas.de",
      "name": "\"Auto-Lardas\" gebr. Ersatzteile, Export, Kfz-Handel oHG",
      "logo": "https://img.logo.dev/auto-lardas.de?token=pk_S-z4OHSVRdqZEzd20vlKcw",
      "industry": "Motor Vehicle Manufacturing",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "city": "Großwallstadt",
      "state": "Bayern",
      "country": "Germany"
    },
    {
      "id": "55ADD000C849B20536327F68AB5B56F9",
      "domain": "dostana-store.de",
      "name": "\"Dostana\" Import Export GmbH",
      "logo": "https://img.logo.dev/dostana-store.de?token=pk_S-z4OHSVRdqZEzd20vlKcw",
      "industry": "Custom computer programming services",
      "revenueRange": "$1 - 9.99 Million",
      "employeeRange": "Small (21-100 Employees)",
      "city": "Hamburg",
      "state": "Hamburg",
      "country": "Germany"
    },
	....
  ]
}

---

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.

---