Find complementary or alternative products related to a given product for a specific company and cohort context.
Use this to power “customers who use X also use Y” and “alternatives to X” surfacing in your UI.

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

Endpoint

GET /companies/{companyDomain}/products/{productId}/related

Path parameters

Name	Type	Required	Description
`companyDomain`	string	Yes	Company domain (e.g. `hilton.com`)
`productId`	string	Yes	Anchor product ID (e.g. `prod_office365`)

Query parameters

Name	Type	Required	Default	Description
`cohort`	`CohortTypeEnum`	Yes	—	One of: `Default`, `Defined`, `Aspirational`
`page`	int	No	0	Page index (0-based)
`size`	int	No	20	Page size (max ~200)

The cohort parameter ensures “relatedness” is computed within the peer context that matters for benchmarking.

Example — Related products in Default cohort

curl -X 'GET' \
  'https://api.salescaddy.ai/api/companies/hilton.com/products/1eb943bd-c649-40ca-896a-a97501d58842/related?cohort=Default&size=20' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN"

const url = "https://api.salescaddy.ai/api/companies/hilton.com/products/prod_office365/related?cohort=Default&page=0&size=10";
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

import os, requests
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 {os.environ['TOKEN']}"})
print(r.json())
``]
```csharp
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/products/prod_office365/related?cohort=Default&page=0&size=10");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

[
   {
    "id": "9f526c69ea6308647372db659c234aad",
    "name": "Microsoft SQL Server 2008",
    "description": "Microsoft SQL Server 2008 is a database management platform designed for database administrators. It enables users to consolidate servers and manage large-scale online transactional processing, infer and build applications for redistribution by ISVs, establish search engines and dashboards, as well as accomplish auditing DDL (data definition language) commands. Features include performance management, data warehousing, remote synchronization capability, SQL Server Management Studio integration, and backup stream compression capability.",
    "logo": "https://logo.clearbit.com/microsoft.com",
    "category": "Database Management Systems (DBMS)",
    "reviewCount": 1078,
    "starRating": 3.856066942214966,
    "avgRating": 3.286586284637451,
    "vendor": {
      "domain": "microsoft.com",
      "name": "Microsoft",
      "logo": "https://img.logo.dev/microsoft.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    "categoryId": "bd009baa-4ca7-4b2e-9f62-7477e053bda8"
  },
  {
    "id": "9022f657aacdd38f9b92dd4c7ed35514",
    "name": "Microsoft SQL Server Integration Services",
    "description": "Microsoft SQL Server Integration Services is an enterprise-level data integration and data transformation solution designed for businesses across industries. It enables users to copy or download files to solve business problems, extract and transform data from XML files, flat files, and relational data sources, and manage SQL server objects and data. Features include data warehouse loading, data mining, built-in tasks, graphical tools, and an SSIS catalog database.",
    "logo": "https://logo.clearbit.com/microsoft.com",
    "category": "Database Management Systems (DBMS)",
    "reviewCount": 1374,
    "starRating": 3.660961627960205,
    "avgRating": 3.346970319747925,
    "vendor": {
      "domain": "microsoft.com",
      "name": "Microsoft",
      "logo": "https://img.logo.dev/microsoft.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    "categoryId": "bd009baa-4ca7-4b2e-9f62-7477e053bda8"
  },
  {
    "id": "d9648c15ba0bbde9eed9ed9bb11b248a",
    "name": "Oracle 10g",
    "description": "Oracle 10g is a grid computing management solution designed for database administrators. It enables users to execute on the processor in different size servers; monitor database activity and manage database users, storage, and memory; set up a development environment or shared database server; automate database management tasks; install a database over multiple servers through real application cluster (RAC) components. Features include resource sharing, automatic load balancing, data provisioning, transparent data encryption, and media formats support.",
    "logo": "https://logo.clearbit.com/oracle.com",
    "category": "Database Management Systems (DBMS)",
    "reviewCount": 1399,
    "starRating": 3.9496679306030273,
    "avgRating": 3.7098565101623535,
    "vendor": {
      "domain": "oracle.com",
      "name": "Oracle",
      "logo": "https://img.logo.dev/oracle.com?token=pk_S-z4OHSVRdqZEzd20vlKcw"
    },
    "categoryId": "bd009baa-4ca7-4b2e-9f62-7477e053bda8"
  },
....
]

Example — Aspirational cohort

curl -X 'GET' \
  'https://api.salescaddy.ai/api/companies/hilton.com/products/1eb943bd-c649-40ca-896a-a97501d58842/related?cohort=Aspirational&size=20' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN"

const url = "https://api.salescaddy.ai/api/companies/hilton.com/products/prod_azure/related?cohort=Aspirational&page=0&size=10";
console.log(await (await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } })).json());

r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/products/prod_azure/related",
                 params={"cohort":"Aspirational","page":0,"size":10},
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/products/prod_azure/related?cohort=Aspirational&page=0&size=10");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Use cases & tips

Cross‑sell and attach — show complementary tools commonly found with the anchor product in the chosen cohort.
Alternatives comparison — surface nearby substitutes users evaluate alongside the anchor.
Cohort matters — Default for broad baseline, Defined for curated peer group, Aspirational for forward‑looking stacks.
Pair with Usage Metrics to rank related items by adoption/intensity in the cohort.
For deterministic presence checks, call Products‑in‑Use for the returned productIds.

Errors

Code	Meaning	How to fix
400	Bad request	Validate `cohort` value and `page/size`.
401	Unauthorized	Provide/refresh Bearer token.
403	Forbidden	Check client permissions.
404	Not found	Unknown `companyDomain` or `productId`; or no related products.
429	Rate limit exceeded	Retry with exponential backoff; respect `Retry-After`.
500	Internal server error	Retry later; contact support if persistent.