Companies - Usage Metrics

Benchmark technology usage within a cohort for a given company.
Returns normalized metrics per product (0.0–1.0), so you can rank adoption and identify gaps.

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

---

Endpoint

GET /companies/{companyDomain}/cohort/{cohort}/metrics/usage

Path parameters

Name	Type	Required	Description
companyDomain	string	Yes	Subject company domain (e.g. hilton.com)
cohort	CohortTypeEnum	Yes	Default | Defined | Aspirational

Query parameters

Name	Type	Required	Description
vendorDomain	string	No	Filter results to a single vendor (e.g., microsoft.com)
productId	string	No	Filter results to a single product ID (e.g., prod_office365)

The response is a JSON array of UsageMetricDTO (not paginated). Use filters to reduce payload size.

UsageMetricDTO (trimmed, conceptual)

JSON

{
  "productId": "prod_office365",
  "productName": "Microsoft 365",
  "vendorDomain": "microsoft.com",
  "adoption": 0.68,
  "intensity": 0.74,
  "penetration": 0.71
}

Metric semantics (high level)

• adoption — share of cohort companies that use the product (0.0–1.0).
• intensity — relative depth/strength of the product’s presence in the cohort (0.0–1.0).
• penetration — breadth of adoption across the cohort (0.0–1.0).

---

Example — Filter by vendorDomain

Bash

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

Node

const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?vendorDomain=microsoft.com";
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

import os, requests
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage",
                 params={"vendorDomain":"microsoft.com"},
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

using System.Net.Http.Headers;
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", TOKEN);
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):

JSON

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

---

Example — Filter by productId

Bash

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

Node

const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?productId=prod_office365";
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage",
                 params={"productId":"prod_office365"},
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?productId=prod_office365");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

JSON

[
  { "productId":"prod_office365", "productName":"Microsoft 365", "vendorDomain":"microsoft.com", "adoption":0.68, "intensity":0.74, "penetration":0.71 }
]

---

Example — All metrics (no filter)

Use client‑side sorting to rank by a metric (e.g., adoption) and take top N.

Bash

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

Node

const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage";
const data = await (await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } })).json();
console.log(data.slice(0, 5)); // first 5

Python

r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage",
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
data = r.json()
print(data[:5])  # first 5

C#

var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage");
Console.WriteLine((await res.Content.ReadAsStringAsync()).Substring(0, 400) + "...");

---

Example — Top 5 by adoption (client‑side rank)

Bash

curl -sS "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage" \
  -H "Authorization: Bearer $TOKEN" | jq -r '[.[]] | sort_by(-.adoption) | .[:5]'

Node

const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage";
const data = await (await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } })).json();
const top = data.sort((a,b)=>b.adoption-a.adoption).slice(0,5);
console.log(top);

Python

import operator
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage",
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
top = sorted(r.json(), key=operator.itemgetter("adoption"), reverse=True)[:5]
print(top)

C#

using System.Text.Json;
var json = await (await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage")).Content.ReadAsStringAsync();
var items = JsonSerializer.Deserialize<List<Dictionary<string,object>>>(json);
var top = items.OrderByDescending(i => Convert.ToDouble(i["adoption"])).Take(5);
Console.WriteLine(JsonSerializer.Serialize(top));

---

Notes & best practices

• Metrics are normalized (0.0–1.0) — perfect for ranking & visualizations.
• Results are not paginated; use vendorDomain/productId to reduce size if needed.
• Sorting is not guaranteed — sort on the client (e.g., by adoption or intensity).
• For deterministic validation, pair with:
  • POST /companies/{domain}/products-in-use — confirm presence of specific products.
  • GET /companies/{domain}/products/paged — fetch installed products with details.

---

Errors

Code	Meaning	How to fix
400	Bad request	Validate cohort enum and filter types.
401	Unauthorized	Provide/refresh Bearer token.
403	Forbidden	Check client permissions.
404	Not found	Unknown companyDomain or cohort not configured.
429	Rate limit exceeded	Retry with exponential backoff; respect Retry-After.
500	Internal server error	Retry later; contact support if persistent.

---