API Reference
Start typing to search…

Recommended Workflow

This guide shows a practical end‑to‑end flow for integrating BuyerCaddy into your product:
Company → Competitors → Cohorts → Usage Metrics → Products → Related Products → Firmographics & Feed → (Optional) AI

Audience: Developers / integrators.
All examples include bash / node / python / csharp tabs (put as adjacent code blocks).
Base URL: https://api.salescaddy.ai/api

Step 0 — Authentication (prerequisite)

Obtain a Bearer token via OAuth2 Client Credentials (Auth0) and pass it to every request: Authorization: Bearer $TOKEN.

Example Auth

curl -sS -X POST "https://pawannachnani.us.auth0.com/oauth/token" -H "Content-Type: application/json" -d '{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret":"YOUR_CLIENT_SECRET",
  "audience":"https://api.salescaddy.ai",
  "grant_type":"client_credentials"
}' | jq -r '.access_token'

export TOKEN="PASTE_TOKEN_HERE"
const res = await fetch("https://pawannachnani.us.auth0.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    audience: "https://api.salescaddy.ai",
    grant_type: "client_credentials"
  })
});
const { access_token: TOKEN } = await res.json();
import requests, os
r = requests.post("https://pawannachnani.us.auth0.com/oauth/token", json={
  "client_id":"YOUR_CLIENT_ID",
  "client_secret":"YOUR_CLIENT_SECRET",
  "audience":"https://api.salescaddy.ai",
  "grant_type":"client_credentials"
})
TOKEN = r.json()["access_token"]
using System.Net.Http.Headers;
var http = new HttpClient();
var res = await http.PostAsJsonAsync("https://pawannachnani.us.auth0.com/oauth/token", new {
  client_id="YOUR_CLIENT_ID",
  client_secret="YOUR_CLIENT_SECRET",
  audience="https://api.salescaddy.ai",
  grant_type="client_credentials"
});
var token = (await res.Content.ReadFromJsonAsync<Dictionary<string,object>>())["access_token"]?.ToString();

Step 1 — Search Companies (discovery)

Use filters (industry, size, countries, product signals, etc.) to find target companies.

Endpoint: POST /companies/search
Headers: Authorization: Bearer ... (+ X-On-Behalf-Of-User if export=true)
Query: export=false (default) — set true to trigger file export.

Example Search

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", "employeeRange":["1001-5000","10001+"], "countries":["US","DE"] }'
const res = await fetch("https://api.salescaddy.ai/api/companies/search?export=false", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ query:"hospitality", employeeRange:["1001-5000","10001+"], countries:["US","DE"] })
});
console.log(await res.json());
import requests, os, json
payload = { "query":"hospitality", "employeeRange":["1001-5000","10001+"], "countries":["US","DE"] }
r = requests.post("https://api.salescaddy.ai/api/companies/search?export=false",
                  headers={"Authorization": f"Bearer {TOKEN}", "Content-Type":"application/json"},
                  data=json.dumps(payload))
print(r.json())
using System.Text.Json;
var body = JsonSerializer.Serialize(new { query="hospitality", employeeRange=new[]{"1001-5000","10001+"}, countries=new[]{"US","DE"} });
var req = new StringContent(body, System.Text.Encoding.UTF8, "application/json");
var res = await http.PostAsync("https://api.salescaddy.ai/api/companies/search?export=false", req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

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

Step 2 — Competitors (peer list)

Find similar companies (up to 50).

Endpoint: GET /companies/{companyDomain}/competitors

Example Competitors

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/competitors?page=0&size=10" -H "Authorization: Bearer $TOKEN"
const url = "https://api.salescaddy.ai/api/companies/hilton.com/competitors?page=0&size=10";
console.log(await (await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } })).json());
import requests, os
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/competitors",
                 params={"page":0,"size":10},
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json())
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/competitors?page=0&size=10");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

{
  "totalPages": 3,
  "totalElements": 47,
  "content": [
    { "domain":"marriott.com", "name":"Marriott International", "employeeRange":"10001+" },
    { "domain":"hyatt.com", "name":"Hyatt Hotels Corporation", "employeeRange":"5001-10000" }
  ]
}

Step 3 — Cohorts (Default / Defined / Aspirational)

Get cohort members for the company. Start with Default for a broad baseline.

Endpoint: GET /companies/{companyDomain}/cohort/{cohort}

Example Cohort

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default?page=0&size=10" -H "Authorization: Bearer $TOKEN"
const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default?page=0&size=10";
console.log(await (await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } })).json());
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default",
                 params={"page":0,"size":10},
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json())
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default?page=0&size=10");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

{
  "totalPages": 5,
  "totalElements": 98,
  "content": [
    { "domain":"hyatt.com", "name":"Hyatt Hotels Corporation" },
    { "domain":"ihg.com", "name":"InterContinental Hotels Group" }
  ]
}

Step 4 — Usage Metrics (benchmarking)

Benchmark adoption/intensity/penetration within a selected cohort. Filter by vendorDomain or productId as needed.

Endpoint: GET /companies/{domain}/cohort/{cohort}/metrics/usage

Example Usage Metrics

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?vendorDomain=microsoft.com" -H "Authorization: Bearer $TOKEN"
const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?vendorDomain=microsoft.com";
console.log(await (await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } })).json());
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage",
                 params={"vendorDomain":"microsoft.com"},
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json())
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?vendorDomain=microsoft.com");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

[
  { "productId":"prod_office365", "productName":"Microsoft 365", "adoption":0.68, "intensity":0.74, "penetration":0.71 },
  { "productId":"prod_azure", "productName":"Microsoft Azure", "adoption":0.52, "intensity":0.60, "penetration":0.55 }
]

Step 5 — Company Products (choose output format)

Three flavors depending on your integration needs:

  1. CSV — bulk export (file)
  2. JSONL — line-delimited JSON stream
  3. Paged JSON — standard paginated list

Example Products — CSV

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/products?export=true"   -H "Authorization: Bearer $TOKEN"   -H "X-On-Behalf-Of-User: [email protected]" -o hilton-products.csv
const res = await fetch("https://api.salescaddy.ai/api/companies/hilton.com/products?export=true", {
  headers: { Authorization: `Bearer ${TOKEN}`, "X-On-Behalf-Of-User":"[email protected]" }
});
const buf = await res.arrayBuffer(); /* save to file */
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/products",
                 params={"export":"true"},
                 headers={"Authorization": f"Bearer {TOKEN}", "X-On-Behalf-Of-User":"[email protected]"})
open("hilton-products.csv","wb").write(r.content)
http.DefaultRequestHeaders.Add("X-On-Behalf-Of-User","[email protected]");
var bytes = await http.GetByteArrayAsync("https://api.salescaddy.ai/api/companies/hilton.com/products?export=true");
System.IO.File.WriteAllBytes("hilton-products.csv", bytes);

Example Products — JSONL

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/products/json?export=false" -H "Authorization: Bearer $TOKEN"
const res = await fetch("https://api.salescaddy.ai/api/companies/hilton.com/products/json?export=false",
  { headers: { Authorization: `Bearer ${TOKEN}` } });
console.log(await res.text()); // parse by lines
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/products/json",
                 params={"export":"false"},
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.text.splitlines()[:3])  # first 3 lines
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/products/json?export=false");
var text = await res.Content.ReadAsStringAsync();
Console.WriteLine(text.Split('\n')[0]);

Example Products — Paged JSON

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/products/paged?page=0&size=20" -H "Authorization: Bearer $TOKEN"
const url = "https://api.salescaddy.ai/api/companies/hilton.com/products/paged?page=0&size=20";
console.log(await (await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } })).json());
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/products/paged",
                 params={"page":0,"size":20},
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json())
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/products/paged?page=0&size=20");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

{
  "totalPages": 12,
  "totalElements": 237,
  "content": [
    { "companyDomain":"hilton.com", "productId":"prod_office365", "productName":"Microsoft 365", "vendorDomain":"microsoft.com", "intensity":0.78 },
    { "companyDomain":"hilton.com", "productId":"prod_slack", "productName":"Slack", "vendorDomain":"salesforce.com", "intensity":0.55 }
  ]
}

Step 6 — Related Products (by company & product)

Complementary or alternative products related to a given product in the company context.

Endpoint: GET /companies/{domain}/products/{productId}/related (with cohort)

Example Related

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/products/prod_office365/related?cohort=Default&page=0&size=10" -H "Authorization: Bearer $TOKEN"
const url = "https://api.salescaddy.ai/api/companies/hilton.com/products/prod_office365/related?cohort=Default&page=0&size=10";
console.log(await (await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } })).json());
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/products/prod_office365/related",
                 params={"cohort":"Default","page":0,"size":10},
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json())
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/products/prod_office365/related?cohort=Default&page=0&size=10");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

[
  { "id":"prod_slack", "name":"Slack", "category":"Collaboration", "vendor":{ "domain":"salesforce.com" } },
  { "id":"prod_zoom", "name":"Zoom", "category":"Collaboration", "vendor":{ "domain":"zoom.us" } }
]

Step 7 — Firmographics & Feed

Get firmographic snapshot and a company news/events feed (with pagination cursor).

Endpoints:

  • GET /companies/{domain}/firmographics
  • GET /companies/{domain}/feed (use paginationId to fetch next batch)

Example Firmographics

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/firmographics" -H "Authorization: Bearer $TOKEN"
console.log(await (await fetch("https://api.salescaddy.ai/api/companies/hilton.com/firmographics",
  { headers: { Authorization: `Bearer ${TOKEN}` } })).json());
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/firmographics",
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json())
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/firmographics");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample firmographics (trimmed):

{ "domain":"hilton.com", "name":"Hilton", "employeeRange":"10001+", "revenueRange":"10B+", "industry":"Hospitality" }

Example Feed

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/feed" -H "Authorization: Bearer $TOKEN"
const res = await fetch("https://api.salescaddy.ai/api/companies/hilton.com/feed", { headers: { Authorization: `Bearer ${TOKEN}` }});
console.log(await res.json());
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/feed",
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json())
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/feed");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample feed (trimmed):

{
  "paginationId":"eyJvZmZzZXQiOjEwMH0=",
  "items":[
    { "id":"evt_001", "title":"Hilton partners with XYZ", "publishedAt":"2025-07-12T10:00:00Z", "category":"PARTNERSHIP", "url":"https://news.example/hilton-xyz" },
    { "id":"evt_002", "title":"New data center expansion", "publishedAt":"2025-07-10T09:30:00Z", "category":"INFRASTRUCTURE", "url":"https://news.example/hilton-dc" }
  ]
}

Step 8 — Optional AI Helpers (discovery → verify deterministically)

Use AI for rapid hypothesis generation, then verify via deterministic endpoints (products‑in‑use, paged products, usage metrics).
Required header: X-On-Behalf-Of-User: <email>

Example AI — Find Customers of Products

curl -sS -X POST "https://api.salescaddy.ai/api/ai/find-customers-of-products?prompt=Who%20uses%20Snowflake%3F&size=10"   -H "Authorization: Bearer $TOKEN" -H "X-On-Behalf-Of-User: [email protected]"
const url = "https://api.salescaddy.ai/api/ai/find-customers-of-products?prompt=Who%20uses%20Snowflake%3F&size=10";
console.log(await (await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}`, "X-On-Behalf-Of-User":"[email protected]" } })).json());
r = requests.post("https://api.salescaddy.ai/api/ai/find-customers-of-products",
                  params={"prompt":"Who uses Snowflake?","size":10},
                  headers={"Authorization": f"Bearer {TOKEN}", "X-On-Behalf-Of-User":"[email protected]"})
print(r.json())
http.DefaultRequestHeaders.Add("X-On-Behalf-Of-User","[email protected]");
var res = await http.PostAsync("https://api.salescaddy.ai/api/ai/find-customers-of-products?prompt=Who%20uses%20Snowflake%3F&size=10", null);
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample AI result (trimmed):

[
  { "companyDomain":"acme.com", "companyName":"Acme Inc.", "confidence":0.82 },
  { "companyDomain":"example.org", "companyName":"Example Org", "confidence":0.77 }
]

Troubleshooting & Best Practices

  • 401 Unauthorized → refresh token; ensure Authorization: Bearer <token> is set.
  • 404 Not Found → check companyDomain/productId spelling (no www.).
  • 429 Rate Limit → retry with exponential backoff (1s → 2s → 4s).
  • AI endpoints → always include X-On-Behalf-Of-User.
  • Pagination → defaults page=0, size=20 (cap ≈ 200).
  • Exports → pass export=true and X-On-Behalf-Of-User for CSV.
  • Verification → confirm AI leads via /products-in-use, /products/paged, and /metrics/usage.

What’s next?

  • Companies Reference: search, competitors, cohorts, metrics, products, related, firmographics, feed.
  • AI Best Practices: writing effective prompts; verification patterns.
  • Profiles (separate flow): /profiles/search → /profiles/purchase → /profiles/{id}.