Quick Start

Get an OAuth Bearer token
Make your first test call
Run a 5-minute end-to-end flow: Company → Competitors → Cohort → Usage Metrics → Products → (optional) AI helper
Learn common gotchas (401/429), pagination, and best practices

1) Prerequisites

Base URL: https://api.salescaddy.ai/api
Auth: OAuth2 Client Credentials (get token from Auth0, then use Authorization: Bearer … on every request)
Formats: JSON by default; some endpoints can return CSV/JSONL (noted below).

Tip: Keep an environment variable for the token to avoid copy-pasting.

2) Get a 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 } = await res.json();

import requests
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 json = await res.Content.ReadFromJsonAsync<Dictionary<string,object>>();
var token = json["access_token"].ToString();

3) Hello, API — first call

We’ll list vendors. Endpoint: GET /vendors

Example Get Vendors

curl -sS "https://api.salescaddy.ai/api/vendors?page=0&size=10"   -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://api.salescaddy.ai/api/vendors?page=0&size=10", {
  headers: { Authorization: `Bearer ${process.env.TOKEN}` }
});
console.log(await res.json());

import os, requests
r = requests.get(
  "https://api.salescaddy.ai/api/vendors",
  params={"page":0,"size":10},
  headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", TOKEN);
var res = await http.GetAsync("https://api.salescaddy.ai/api/vendors?page=0&size=10");
Console.WriteLine(await res.Content.ReadAsStringAsync());

4) The 5-minute end-to-end flow

Step 1 — Competitors

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/competitors?page=0&size=10"   -H "Authorization: Bearer $TOKEN"

Step 2 — Cohorts

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default?page=0&size=10"   -H "Authorization: Bearer $TOKEN"

Step 3 — Usage Metrics

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?vendorDomain=microsoft.com"   -H "Authorization: Bearer $TOKEN"

Step 4 — Company Products (paged JSON)

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/products/paged?page=0&size=20"   -H "Authorization: Bearer $TOKEN"

Step 5 — Verify Product In Use

curl -sS -X POST "https://api.salescaddy.ai/api/companies/hilton.com/products-in-use"   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{ "productIds": ["prod_office365","prod_slack"] }'

Optional — AI Helper

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]"

5) Pagination & defaults

page default: 0
size default: 20
max size ≈ 200

6) Troubleshooting

401 Unauthorized → refresh token, check header format.
404 Not Found → verify domain/productId spelling.
429 Rate Limit → retry with exponential backoff.
AI endpoints → must pass X-On-Behalf-Of-User.