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

const TOKEN = process.env.TOKEN;

const response = await fetch(
  "https://api.salescaddy.ai/api/companies/search?export=false",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      page: 0,
      size: 10,
      filter: {
        companyNameContains: "string",
        vendorDomainInAnd: false,
        vendorDomainNotInAnd: false,
        productIdInAnd: false,
        productIdNotInAnd: false,
        mainCategoryIdInAnd: false,
        mainCategoryIdNotInAnd: false,
        intensityBucketIn: ["LOW"],
        dateLastVerifiedBucketIn: ["ANCIENT"]
      }
    })
  }
);

const data = await response.json();
console.log(data);

import requests
import os

TOKEN = os.getenv("TOKEN")

url = "https://api.salescaddy.ai/api/companies/search?export=false"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

payload = {
    "page": 0,
    "size": 10,
    "filter": {
        "companyNameContains": "string",
        "vendorDomainInAnd": False,
        "vendorDomainNotInAnd": False,
        "productIdInAnd": False,
        "productIdNotInAnd": False,
        "mainCategoryIdInAnd": False,
        "mainCategoryIdNotInAnd": False,
        "intensityBucketIn": ["LOW"],
        "dateLastVerifiedBucketIn": ["ANCIENT"]
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var token = Environment.GetEnvironmentVariable("TOKEN");

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

var payload = new
{
    page = 0,
    size = 10,
    filter = new
    {
        companyNameContains = "string",
        vendorDomainInAnd = false,
        vendorDomainNotInAnd = false,
        productIdInAnd = false,
        productIdNotInAnd = false,
        mainCategoryIdInAnd = false,
        mainCategoryIdNotInAnd = false,
        intensityBucketIn = new[] { "LOW" },
        dateLastVerifiedBucketIn = new[] { "ANCIENT" }
    }
};

var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.salescaddy.ai/api/companies/search?export=false",
    content
);

var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);

Sample response (trimmed):

{
  "totalPages": 304,
  "totalElements": 3035,
  "content": [
    {
      "id": "34B577BE20FBC15477AADB9A08101FF9",
      "domain": "string1",
      "logo": "https://img.logo.dev/string1?token=...",
      "industry": "string",
      "revenueRange": "$10 - 49.99 Million",
      "phone": "string",
      "employeeRange": "Small (21-100 Employees)",
      "city": "string",
      "state": "string",
      "country": "United States"
    },
    {
      "id": "91C0C59C8F6FC9AA2DC99A89F2FD0AB5",
      "domain": "string2",
      "logo": "https://img.logo.dev/string2?token=...",
      "industry": "General Services - Business",
      "revenueRange": "$10 - 49.99 Million",
      "phone": "string",
      "employeeRange": "Small (21-100 Employees)",
      "city": "string",
      "state": "string",
      "country": "United States"
    },
    {
      "id": "B45CFFE084DD3D20D928BEE85E7B0F21",
      "domain": "string",
      "logo": "https://img.logo.dev/string?token=...",
      "industry": "string",
      "revenueRange": "$10 - 49.99 Million",
      "phone": "string",
      "employeeRange": "Small (21-100 Employees)",
      "city": "string",
      "state": "string",
      "country": "United States"
    },
    {
      "id": "44646D4B5D99570D2F006BAA82E93F7D",
      "domain": "clearstrings.com.au",
      "name": "#1 Beautiful Live Music For Your Event I Clear Strings",
      "logo": "https://img.logo.dev/clearstrings.com.au?token=...",
      "industry": "General Services - Business",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "city": "Milton",
      "state": "Ontario",
      "country": "Canada"
    },
    {
      "id": "EE37C505A148AA377B8EC677457DAA14",
      "domain": "tmstringer.com",
      "name": "#TMStringer – Portable Stringing Machine",
      "logo": "https://img.logo.dev/tmstringer.com?token=...",
      "industry": "General Services - Business",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "country": "Brazil"
    },
    {
      "id": "FA96FAD979D8E693E7273352AB43FD13",
      "domain": "1stringsportstraining.com",
      "name": "1 String Sports Perfo",
      "logo": "https://img.logo.dev/1stringsportstraining.com?token=...",
      "industry": "Nonclassifiable establishments",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "city": "Virginia Beach",
      "state": "Virginia",
      "country": "United States"
    },
    {
      "id": "7D833F03141DBFE7463BC8BF98E1413B",
      "domain": "12stringbrewingco.com",
      "name": "12 String Brewing Co",
      "logo": "https://img.logo.dev/12stringbrewingco.com?token=...",
      "industry": "Eating places",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "city": "Spokane Valley",
      "state": "Washington",
      "country": "United States"
    },
    {
      "id": "1160A941AFA3679A321F7F6025265455",
      "domain": "12stringstudios.com",
      "name": "12 String Studios",
      "logo": "https://img.logo.dev/12stringstudios.com?token=...",
      "industry": "Schools and educational services",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "city": "Saskatoon",
      "state": "Saskatchewan",
      "country": "Canada"
    },
    {
      "id": "04CF5958D0017A9F3D7B9E15A3592BE5",
      "domain": "12stringtim.com",
      "name": "12 String Tim",
      "logo": "https://img.logo.dev/12stringtim.com?token=...",
      "industry": "Film/Video/Theatrical Production & Services",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Small (21-100 Employees)",
      "city": "San Benito",
      "state": "TX",
      "country": "United States"
    },
    {
      "id": "0B644DDD511BA51657DC563CCDD54213",
      "domain": "forerunnerva.com",
      "name": "12 Strings Audio/Video Network, LLC",
      "logo": "https://img.logo.dev/forerunnerva.com?token=pk_S-z4OHSVRdqZEzd20vlKcw",
      "industry": "Commercial art and graphic design",
      "revenueRange": "Less than $1 Million",
      "employeeRange": "Micro (1-20 Employees)",
      "city": "Suffolk",
      "state": "Virginia",
      "country": "United States"
    }
  ]
}

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=20" -H "Authorization: Bearer $TOKEN"

const url = "https://api.salescaddy.ai/api/companies/hilton.com/competitors?page=0&size=20";
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":20},
                 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=20");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

{
  "totalPages": 3,
  "totalElements": 47,
  "content": [
    {
      "domain": "hosthotels.com",
      "name": "Host Hotels & Resorts",
      "logo": "https://img.logo.dev/hosthotels.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    {
      "domain": "kerzner.com",
      "name": "Kerzner International",
      "logo": "https://img.logo.dev/kerzner.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    {
      "domain": "atriumhospitality.com",
      "name": "Atrium Hospitality",
      "logo": "https://img.logo.dev/atriumhospitality.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    {
      "domain": "kempinski.com",
      "name": "Kempinski AG",
      "logo": "https://img.logo.dev/kempinski.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    ...
  ]
}

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=20" -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": 10412,
  "totalElements": 208229,
  "content": [
    {
      "domain": "hotellauri.it",
      "name": "S.I.C.T.A. SAS DI SCHEGGIA ARIANNA SEVERINE",
      "logo": "https://img.logo.dev/hotellauri.it?token=..."
    },
    {
      "domain": "hotel-restaurant-rabennest.de",
      "name": "Ilona Lemm-Hirsch",
      "logo": "https://img.logo.dev/hotel-restaurant-rabennest.de?token=..."
    },
    {
      "domain": "villamiralbenga.com",
      "name": "MICRO DOMUS DI ROBERTA GIANFAGNA",
      "logo": "https://img.logo.dev/villamiralbenga.com?token=..."
    },
    {
      "domain": "tachicklakeresort.com",
      "name": "513138 BC Ltd",
      "logo": "https://img.logo.dev/tachicklakeresort.com?token=..."
    },
    ....
]

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):

[
  {
    "percentage": 15,
    "product": "microsoft 365 apps & services",
    "category": "Collaboration & Productivity"
  },
  {
    "percentage": 1,
    "product": "microsoft skype",
    "category": "Collaboration & Productivity"
  },
  {
    "percentage": 10,
    "product": "microsoft exchange online",
    "category": "Calendar"
  },
  {
    "percentage": 2,
    "product": "microsoft outlook",
    "category": "Calendar"
  },
  {
    "percentage": 11,
    "product": "microsoft exchange",
    "category": "Email Management"
  },
	...
]

Step 5 — Company Products (choose output format)

Three flavors depending on your integration needs:

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

Example Products — CSV

curl -X GET \
  "https://api.salescaddy.ai/api/companies/microsoft.com/products?export=true" \
  -H "Accept: text/csv" \
  -H "Authorization: Bearer $TOKEN"

curl -X GET \
  "https://api.salescaddy.ai/api/companies/microsoft.com/products?export=true" \
  -H "Accept: text/csv" \
  -H "Authorization: Bearer $TOKEN"

import os
import requests

TOKEN = os.getenv("TOKEN")

url = "https://api.salescaddy.ai/api/companies/microsoft.com/products?export=true"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Accept": "text/csv"
}

response = requests.get(url, headers=headers)
response.raise_for_status()

with open("microsoft_products.csv", "w", encoding="utf-8") as f:
    f.write(response.text)

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var token = Environment.GetEnvironmentVariable("TOKEN"); // или строкой

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", token);
        client.DefaultRequestHeaders.Accept.Add(
            new MediaTypeWithQualityHeaderValue("text/csv"));

        var url = "https://api.salescaddy.ai/api/companies/microsoft.com/products?export=true";

        var response = await client.GetAsync(url);
        response.EnsureSuccessStatusCode();

        var csv = await response.Content.ReadAsStringAsync();
        Console.WriteLine(csv);
    }
}

Example Products — JSON

curl -X 'GET' \ 'https://api.salescaddy.ai/api/companies/microsoft.com/products/json?export=false' \
  -H 'accept: application/json' \ -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]);

{
"id":"FCFDDBA99F6C8859090214408868B39C",
"companyId":"FF5C054C7CD6924C570F944007CCF076",
"company":"Microsoft Corporation",
"companyDomain":"microsoft.com",
"industry":"Computer related services",
"city":"Redmond",
"state":"Washington",
"postalCode":"98052",
"country":"United States",
"phone":null,
"revenueRange":"$1+ Billion",
"employeeRange":"XLarge (5001+ Employees)",
"vendorDomain":"theassessmentcompany.com",
"vendor":"The Assessment Company",
"vendorId":"07a11ede-75be-4801-8276-57f9d860e51f",
"productId":"626f50b6-5c75-4850-8d48-a8deb4e2ebad",
...
"hitCount":327
},
....

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/microsoft.com/products/626f50b6-5c75-4850-8d48-a8deb4e2ebad/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": "add9e735-0879-4550-a340-242c89b92133",
    "name": "iCIMS SkillSurvey Reference",
    "description": "iCIMS SkillSurvey makes the referencing checking process simple and easy for job candidates and their references and more efficient and effective for organizations. It helps employers save time and money, grow revenues, and bring employees onboard faster. Find out why we are the leading online reference checking solution helping thousands of organizations check references on more than 130,000 job candidates each month.\n\niCIMS SkillSurvey is the only online reference solution proven to reduce turnover for cause and has several patents. It will help you discover new talent, improve your hiring process and bring the right employees onboard faster. And it also uncovers soft skills and is proven to reduce first-year turnover for cause.\n\nOur customers reach an average of 4 references and have a detailed feedback report in just over a business day by reaching candidates and their references via email or text messaging. Conduct detailed reference checks and get richer more actionable feedback and spend 92% less time. Integration is available with your applicant tracing solution to make it even easier. \nOur online process sends references a link to complete a job-specific survey that allows references to provide ratings on the skills and behaviors (the relevant soft skills) that are proven to drive success for that job. SkillSurvey has the only job-specific survey library developed for hundreds of roles, whether you’re hiring a sales role, customer service, accountant, retail worker, healthcare worker, RN or leadership role. \n\nWith iCIMS SkillSurvey, reference checking is made easy. There is fraud protection to ensure you’re reaching references. Reports average ratings and include written feedback about a candidate’s strengths and weaknesses. There are candidate comparison reports and interview guides to guide your team. \n\nWhy reference check? Hiring risks are greater than ever. Beyond the high costs of turnover and replacement when the wrong hiring decision is made, consider how a single employee can put your organization at risk for potential lawsuits and brand damage that can add up to millions. Now more than ever, you need to know not just whether an employee can do the job, but how they’ll do the job, and this knowledge can best be affirmed by others.",
    "logo": "https://images.g2crowd.com/uploads/product/image/4ce545365a49159c8b1cd19b1bacd945/icims-skillsurvey-reference.png",
    "category": "Reference Check",
    "features": [
      "AI Text Generation",
      "AI Text Summarization",
      "Alerts and Notifications",
      "Automated",
      "Custom branding",
      "Customization",
      "Dashboards",
      "Fraud detection",
      "GDPR Compliant",
      "Identity verification",
      "Integration APIs",
      "Integrations",
      "Internationalization",
      "Interoperability",
      "Mobility",
      "Optimization",
      "Performance",
      "Reporting",
      "Reports",
      "Security and Compliance",
      "Templates",
      "User, Role, and Access Management",
      "Visualization"
    ],
    "reviewCount": 201,
    "starRating": 4.599999904632568,
    "avgRating": 9.169150352478027,
    "vendor": {
      "domain": "icims.com",
      "name": "iCIMS",
      "logo": "https://img.logo.dev/icims.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    "categoryId": "da101144-9923-47f5-acfb-1607f9edc071"
  },
  {
    "id": "87b5217c-12a3-445f-ac43-5a8567803716",
    "name": "HireRight",
    "description": "",
    "logo": "https://images.g2crowd.com/uploads/product/image/cdbdfa57899b73ce76014cf10f034ca0/hireright.jpg",
    "category": "Background Check",
    "features": [
      "AI Text Generation",
      "AI Text Summarization",
      "Alerts and Notifications",
      "Automated",
      "Compliance",
      "Custom branding",
      "Customization",
      "Dashboard",
      "Dashboards",
      "Fraud detection",
      "GDPR Compliant",
      "Identity verification",
      "Integration APIs",
      "Integrations",
      "Internationalization",
      "Interoperability",
      "Messaging",
      "Mobility",
      "Optimization",
      "Payment",
      "Performance",
      "Platform Search",
      "Real-Time Tracking",
      "Reporting",
      "Reports",
      "Screening and Assessments",
      "Security and Compliance",
      "Templates",
      "User, Role, and Access Management",
      "Visualization"
    ],
    "reviewCount": 141,
    "starRating": 3.4000000953674316,
    "avgRating": 6.773049831390381,
    "vendor": {
      "domain": "hireright.com",
      "name": "HireRight",
      "logo": "https://img.logo.dev/hireright.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    "categoryId": "c8760ec3-ca92-4d22-b44f-a785c94e4b92"
  },
  {
    "id": "e35a0c99-736e-4442-a7f9-43491b91f282",
    "name": "HackerRank Developer Skills Platform",
    "description": "HackerRank is a developer skills platform that helps businesses evaluate software developers\nbased on skill. Over 3000+ customers across all industries, including 5 out of the leading 8\ncommercial banks in the U.S., rely on HackerRank's automated skills assessments to evaluate\nand hire technical talent from around the world. More than 21+ million developers (over 30 percent of the global developer population) trust HackerRank to learn and practice coding. Every eight seconds, someone around the world completes a HackerRank assessment. For more\ninformation, visit <a href=\"www.hackerrank.com\">www.hackerrank.com</a>.",
    "logo": "https://images.g2crowd.com/uploads/product/image/060528149c093ad5a64d6d8428c514c5/hackerrank-developer-skills-platform.png",
    "category": "Technical Skills Screening",
    "features": [
      "Additional Tools",
      "AI Text Generation",
      "AI Text Summarization",
      "Coding Development",
      "Content Library",
      "Customization",
      "Dashboard",
      "Dashboards",
      "File Sharing",
      "Integration APIs",
      "Integrations",
      "Internationalization",
      "Interoperability",
      "Messaging",
      "Mobility",
      "Payment",
      "Performance",
      "Reporting",
      "Reports",
      "Soft Skills Testing",
      "Task Management",
      "Technical Screening",
      "Technology",
      "User, Role, and Access Management"
    ],
    "reviewCount": 455,
    "starRating": 4.5,
    "avgRating": 9.090109825134277,
    "vendor": {
      "domain": "hackerrank.com",
      "name": "HackerRank",
      "logo": "https://img.logo.dev/hackerrank.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    "categoryId": "878f592e-3f70-44af-aa6c-1cc0aebb5eaf"
  },
...
]

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):

{
  "acquisition": [
    {
      "amount": "136000000",
      "date": "Wed Feb 15 00:15:22 UTC 2023",
      "name": "Midtown Timeshare Hotel",
      "status": "Acquired",
      "undisclosed": "false"
    },
    {
      "amount": "210000000",
      "company_id": "5720793",
      "date": "Fri Mar 15 04:58:32 UTC 2024",
      "name": "Graduate Hotels",
      "status": "Acquisition Pending",
      "undisclosed": "false",
      "website": "graduatehotels.com"
    },
    {
      "date": "Mon Oct 01 00:00:00 UTC 2012",
      "name": "Triangeln Hotel"
    },
    {
      "company_id": "1403846",
      "date": "Mon Apr 15 15:57:04 UTC 2024",
      "name": "Sydell Group, LLC",
      "status": "Acquired",
      "undisclosed": "true",
      "website": "sydellgroup.com"
    },
    {
      "date": "Sun Oct 15 18:23:03 UTC 2017",
      "name": "Icelandic Seachill",
      "status": "Subsidiary",
      "undisclosed": "true"
    },
    {
      "company_id": "2236200",
      "date": "Thu Feb 19 18:30:00 UTC 2015",
      "name": "Parc",
      "status": "Subsidiary",
      "undisclosed": "true",
      "website": "parc55hotel.com"
    },
    {
      "company_id": "4031816",
      "date": "Wed Feb 18 18:30:00 UTC 2015",
      "name": "Hilton Orlando Bonnet Creek",
      "status": "Subsidiary",
      "undisclosed": "true",
      "website": "hiltonbonnetcreek.com"
    },
    {
      "company_id": "1853241",
      "date": "Thu Feb 19 18:30:00 UTC 2015",
      "name": "Waldorf Astoria Orlando",
      "status": "Subsidiary",
      "undisclosed": "true",
      "website": "waldorfastoriaorlando.com"
    }
  ],
  "ceo": {
    "first_name": "Christopher J. ",
    "image_url": "https://s3.amazonaws.com/owler-image/ceo/Christopher J. _Nassetta_owler_20211101_155819_original.png",
    "last_name": "Nassetta"
  },
  "company_id": 136270,
  "company_type": "Public",
  "description": "Hilton is a Virginia-based hospitality company that owns, manages and franchises a portfolio of hotels and resorts offering services such as lodging and event management.",
  "employee_count": "181000.0",
  "facebook_link": "https://www.facebook.com/Hilton/",
  "founded_date": "1919",
  "funding": [
    {
      "amount": "2352812480",
      "date": "Wed Dec 11 18:30:00 UTC 2013",
      "type": "IPO",
      "undisclosed": "false"
    }
  ],
  "hq_address": {
    "city": "McLean",
    "country": "USA",
    "phone": "1-703-883-1000",
    "postal_code": "22102",
    "state": "US-VA",
    "street1": "7930 Jones Branch Drive"
  },
  "industries": [
    "Travel, Recreation & Leisure"
  ],
  "linkedin_link": "https://www.linkedin.com/company/hilton/",
  "logo_url": "https://s3.amazonaws.com/owler-image/logo/hilton_owler_20170217_083454_original.png",
  "name": "Hilton Worldwide Holdings, Inc.",
  "perm_id": "https://permid.org/1-5040250025",
  "profile_url": "https://www.owler.com/iaApp/136270/hilton-company-profile",
  "revenue": "13362000000",
  "short_name": "Hilton",
  "sic_code": [
    "7011",
    "7011"
  ],
  "stock": {
    "exchange": "NYSE",
    "ticker": "HLT"
  },
  "twitter_link": "https://twitter.com/hiltonhotels",
  "website": "http://www.hiltonworldwide.com/",
  "youtube_link": "https://www.youtube.com/@hilton/"
}

Example Feed

curl -sS "https://api.salescaddy.ai/api/companies/microsoft.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=",
   "feeds": [
    {
      "description": "Microsoft has denied any plans to rewrite Windows 11 using AI and Rust after a LinkedIn post from one of its top-level engineers sparked a wave of online backlash by claiming the company's goal was to \"eliminate every line of C and C++ from Microsoft by 2030.\" Galen Hunt, a principal software engineer responsible for [...]",
      "date": "2025-12-25T12:05:00Z",
      "publisherLogoUrl": "https://image4.owler.com/publisher/startupnewsfyi_original.png",
      "publisherName": "StartupNews fyi",
      "sourceUrl": "https://startupnews.fyi/2025/12/25/microsoft-says-its-not-planning-to-use-ai-to-rewrite-windows-from-c-to-rust/",
      "title": "Microsoft: Microsoft Says It's Not Planning To Use AI To Rewrite Windows From C To Rust",
      "category": "NEWS"
    },
    {
      "description": "Microsoft has admitted that turning on BitLocker on PCs with NVMe SSDs can have a noticeable performance impact.The post Microsoft: Windows 11 BitLocker can slow fast NVMe PCs in gaming/video editing. Historically single-digit overhead appeared first on Windows Latest",
      "date": "2025-12-25T00:02:00Z",
      "publisherLogoUrl": "https://s3.amazonaws.com/owler-image/publisher/windowslatest_original.png",
      "publisherName": "Windows Latest",
      "sourceUrl": "https://www.windowslatest.com/2025/12/25/microsoft-windows-11-bitlocker-can-slow-fast-nvme-pcs-in-gaming-video-editing-historically-single-digit-overhead/",
      "title": "Microsoft: Microsoft: Windows 11 BitLocker can slow fast NVMe PCs in gaming/video editing. Historically single-digit overhead",
      "category": "NEWS"
    },
    {
      "description": "A typosquatted domain impersonating the Microsoft Activation Scripts (MAS) tool was used to distribute malicious PowerShell scripts that infect Windows systems with the 'Cosmali Loader'. [...]",
      "enclosureImageUrl": "https://s3.amazonaws.com/owler-image/feedenclosure/fake-mas-windows-activation-domain-used-to-spread-powershell-malware_20251224_174446_original.jpg",
      "date": "2025-12-24T23:00:00Z",
      "publisherLogoUrl": "https://s3.amazonaws.com/owler-image/publisher/bleepingcomputer_original.png",
      "publisherName": "Bleeping Computer",
      "sourceUrl": "https://www.bleepingcomputer.com/news/security/fake-mas-windows-activation-domain-used-to-spread-powershell-malware/",
      "title": "Microsoft: Fake MAS Windows activation domain used to spread PowerShell malware",
      "category": "NEWS"
    },
     ....
]

}

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):

[
  {
    "companyName": "Amazon Web Services",
    "country": "United States",
    "industry": "Technology/Cloud",
    "howProductIsUsed": "Data infrastructure, internal analytics, partner data exchange",
    "scope": "Enterprise-wide",
    "source": "BuyerCaddy",
    "probability": 90,
    "dateFirstVerified": "2018-12-04T00:00:00Z",
    "dateLastVerified": "2025-11-25T00:00:00Z"
  },
  {
    "companyName": "Oracle Corporation",
    "country": "United States",
    "industry": "Technology/Software",
    "howProductIsUsed": "Internal data warehousing and analytics",
    "scope": "Enterprise-wide",
    "source": "BuyerCaddy",
    "probability": 85,
    "dateFirstVerified": "2011-06-06T00:00:00Z",
    "dateLastVerified": "2025-11-25T00:00:00Z"
  },
  {
    "companyName": "Home Depot, Inc.",
    "country": "United States",
    "industry": "Retail",
    "howProductIsUsed": "Supply chain optimization, sales forecasting, inventory management",
    "scope": "Enterprise-wide",
    "source": "BuyerCaddy",
    "probability": 90,
    "dateFirstVerified": "2018-09-05T00:00:00Z",
    "dateLastVerified": "2025-11-25T00:00:00Z"
  },
	...
]

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}.