Competitor List - Wokelo Docs

1. Overview

The Competitor List API generates a ranked list of companies similar to a given seed company, enriched with structured firmographic, funding, and financial data. Given a single company permalink (e.g. "del-air") and an optional set of refinements, Wokelo’s AI pipeline searches its coverage universe of 3M+ companies, evaluates each candidate against the seed company’s product, customers, and business model, and returns a ranked peer set with AI-generated similarity scores and per-company commentary. This is an asynchronous API — submitting a request returns a request_id immediately, and you must poll for status and then retrieve results once the job is complete. Read more about the async pattern in How Async APIs work. Each peer in the result set is returned with:

Identity & firmographics — name, website, HQ location, founding year, ownership type
Product & business profile — product category, AI-generated core offering description, product catalog
Funding & employees — funding stage, total funding raised, investor list, headcount
Financials — revenue, EBITDA, net income, market cap, EV multiples (for public companies)
M&A history — past acquisitions and investments
AI similarity scoring — an Overall Score (1–10) measuring how closely the peer matches the seed company, plus a Commentary paragraph explaining the overlap and differentiation

How it differs from Market Map: Market Map starts from a market topic (e.g. “AI-powered CRM software”); Competitor List starts from a specific company and returns peers most similar to it. Use Competitor List when you have a clear anchor company; use Market Map when you’re defining the universe by category. Common use cases:

Competitive intelligence — Build a competitive battlecard or vendor landscape around a specific company
Peer benchmarking — Identify the right comparable set for valuation, financial benchmarking, or KPI comparisons
Sales & GTM — Map adjacent and competing vendors for partner strategy or competitive deal positioning
M&A roll-up sourcing — Find regional or sub-segment players similar to a platform company for bolt-on consolidation
Investor research — Build a peer set for diligence on a private or public company under evaluation
Sell-side & corp dev — Identify likely competitive intermediaries or strategic peers in a sale process

This API is asynchronous. You submit a job, receive a request_id, poll until status is "COMPLETED", and then read results from the same response. See How Async APIs work.

2. Quick Start

Step 1 — Submit the job

curl --location 'https://api.wokelo.ai/api/enterprise/company-peers/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "company": "del-air",
    "parameters": {
      "detailed_query": "Residential home services companies",
      "sample_companies": ["service-titan", "angi"],
      "geography": ["USA"],
      "company_type": "private"
    }
  }'

import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/company-peers/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "company": "del-air",
        "parameters": {
            "detailed_query": "Residential home services companies",
            "sample_companies": ["service-titan", "angi"],
            "geography": ["USA"],
            "company_type": "private"
        }
    }
)
request_id = response.json()["request_id"]
print("Job submitted:", request_id)

Step 2 — Poll for completion

import time

while True:
    status_resp = requests.get(
        f"https://api.wokelo.ai/api/enterprise/request/{request_id}/status/",
        headers={"Authorization": "Bearer <YOUR_API_TOKEN>"}
    )
    status = status_resp.json()["status"]
    if status == "COMPLETED":
        break
    elif status == "FAILED":
        raise Exception("Job failed")
    print(f"Status: {status} — waiting...")
    time.sleep(5)

Step 3 — Read results

result_resp = requests.get(
    f"https://api.wokelo.ai/api/enterprise/request/{request_id}/result/",
    headers={"Authorization": "Bearer <YOUR_API_TOKEN>"}
)
peers = result_resp.json()["result"]
for p in peers:
    print(p["Name"], "—", p.get("Product Category"), "— Score:", p.get("Overall Score"))

3. Authentication

All requests must include a Bearer token in the Authorization HTTP header. No other authentication method is supported.

Authorization: Bearer <YOUR_API_TOKEN>

API tokens are issued from your Wokelo account. Navigate to Account Details → API Credentials in the Wokelo dashboard to get your client id and client secret. Contact support@wokelo.ai if you do not yet have API access.

Never expose your token in client-side code, browser requests, or public repositories. A missing or invalid token returns 401 Unauthorized. A valid token without sufficient plan permissions returns 403 Forbidden.

4. Request Reference

Endpoint

POST https://api.wokelo.ai/api/enterprise/company-peers/enrich/

The request body is JSON. Only company is required; all parameters fields are optional refinements. The parameters object itself must always be included in the request body — pass empty values ("", [], {}) for any fields you do not want to filter on.

Parameter	Type	Required	Description
`company`	string	Required	Permalink (e.g. `"del-air"`) or full URL of the seed company whose peers you want to find. Use the Company Search API to resolve a permalink if needed.
`parameters.detailed_query`	string	Optional	A natural-language description that refines what “similar” should mean for this run (e.g. focusing on a specific product line, customer segment, or business model). Highly recommended when the seed company is multi-product or operates across multiple segments.
`parameters.sample_companies`	string[]	Optional	Permalinks (e.g. `"service-titan"`) or full URLs of additional representative companies to anchor the peer set. Use when you want to bias results toward a particular flavour of competitor.
`parameters.geography`	string[]	Optional	Geographic scope as ISO country codes (e.g. `["USA", "GBR"]`). Defaults to global if omitted.
`parameters.company_type`	string	Optional	Ownership type filter. Accepted values: `"private"`, `"public"`, `"all"`. Defaults to `"all"`.
`parameters.employee_count`	string[]	Optional	Headcount band filter. Accepted values: `"1-10"`, `"11-50"`, `"51-100"`, `"101-250"`, `"251-500"`, `"501-1000"`, `"1001-5000"`, `"5001-10000"`, `"10000+"`. Empty array = all.
`parameters.founded_year`	object	Optional	Filter by founding year. Accepts `{ "from": 2010 }`, `{ "to": 2020 }`, or both.
`parameters.funding_stage`	string[]	Optional	Filter by most-recent funding stage. Accepted values: `"Non-Equity Assistance"`, `"Angel round"`, `"Pre-seed"`, `"Seed"`, `"Series A"` through `"Series J"`, `"Corporate-Funded"`, `"Debt-Funded"`, `"Private equity round"`, `"Others"`. Empty array = all.
`parameters.total_funding`	object	Optional	Filter by total funding raised in USD. Accepts `{ "from": 1000000 }`, `{ "to": 50000000 }`, or both.
`parameters.last_funding_round`	object	Optional	Filter by last funding round size in USD. Accepts `from` and/or `to` values.
`parameters.revenue`	object	Optional	Filter by annual revenue in USD. Accepts `from` and/or `to` values. Most useful when combined with `company_type: "public"`.
`parameters.ebitda`	object	Optional	Filter by EBITDA (USD). Accepts `from` and/or `to` values.
`parameters.net_income`	object	Optional	Filter by net income (USD). Accepts `from` and/or `to` values.
`parameters.ev_ebitda`	object	Optional	Filter by EV/EBITDA multiple. Accepts `from` and/or `to` values.

Full request example:

curl --location 'https://api.wokelo.ai/api/enterprise/company-peers/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "company": "del-air",
    "parameters": {
      "detailed_query": "Residential HVAC, plumbing, and electrical service contractors",
      "sample_companies": ["wrench-group", "horizon-services"],
      "geography": ["USA"],
      "company_type": "private",
      "employee_count": ["101-250", "251-500", "501-1000"],
      "founded_year": { "from": 1980 }
    }
  }'

import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/company-peers/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "company": "del-air",
        "parameters": {
            "detailed_query": "Residential HVAC, plumbing, and electrical service contractors",
            "sample_companies": ["wrench-group", "horizon-services"],
            "geography": ["USA"],
            "company_type": "private",
            "employee_count": ["101-250", "251-500", "501-1000"],
            "founded_year": {"from": 1980}
        }
    }
)
print(response.json())

5. Response

Job submission response

When you submit the job, you receive a response immediately with a request_id and an initial status.

{
  "request_id": "450c0d25-c83b-4fc7-8713-f96b63db7843",
  "status": "PENDING"
}

Field	Type	Description
`request_id`	string	Unique identifier for this job. Use it to poll status and retrieve results.
`status`	string	Initial job state. One of `"PENDING"`, `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`.

Completed result response

Once status is "COMPLETED", the result contains a result array of peer company objects.

{
  "request_id": "450c0d25-c83b-4fc7-8713-f96b63db7843",
  "status": "COMPLETED",
  "result": [ ...peer objects... ]
}

Peer object fields

Each object in the result array contains the following fields: Identity & firmographics

Field	Type	Description
`Permalink`	string	Wokelo company identifier (e.g. `"horizon-services"`). Use this with other Wokelo APIs.
`Name`	string	Display name of the peer company.
`Website`	string	Primary domain (e.g. `"horizonservices.com"`).
`HQ City`	string	Headquarters city.
`HQ Country`	string	Headquarters country.
`HQ Continent`	string	Headquarters continent.
`Founded`	string or null	Year the company was founded.
`Type`	string	Ownership type: `"Public"` or `"Private"`.
`Operating Status`	string	Current operational status (e.g. `"Operating"`, `"Acquired"`, `"IPO"`).

Product & business

Field	Type	Description
`Product Category`	string or null	High-level category describing the peer’s primary product (e.g. `"Residential Plumbing HVAC Services"`).
`Core Offering`	string or null	AI-generated paragraph describing the peer’s core business and product.
`Product Catalog`	string or null	Comma-separated list of key products and services offered.

People & funding

Field	Type	Description
`Employees (Crunchbase)`	string	Employee count band from Crunchbase (e.g. `"251-500"`).
`Employees (LinkedIn)`	integer or null	Employee count from LinkedIn. May be null.
`Funding Stage`	string or null	Most recent funding stage (e.g. `"Private equity round"`). May be null for non-funded companies.
`Total Funding`	float or null	Total disclosed funding raised in USD.
`Last Funding Date`	string or null	Date of the most recent funding round (`YYYY-MM-DD`).
`Key Investors`	string[] or null	Array of notable investors.

Financials (primarily for public companies)

Field	Type	Description
`Revenue`	float or null	Annual revenue in USD.
`Ticker`	string or null	Exchange and ticker symbol (e.g. `"NYSE:ABC"`).
`EBITDA`	float or null	Earnings before interest, taxes, depreciation, and amortisation.
`Net Income`	float or null	Net income in USD.
`EBITDA Margin (%)`	float or null	EBITDA as a percentage of revenue.
`Net Income Margin (%)`	float or null	Net income as a percentage of revenue.
`EPS Diluted`	float or null	Diluted earnings per share.
`ROA (%)`	float or null	Return on assets.
`Unlevered FCF`	float or null	Unlevered free cash flow in USD.
`D/E`	float or null	Debt-to-equity ratio.
`Market Cap`	float or null	Market capitalisation in USD.
`Enterprise Value`	float or null	Enterprise value in USD.
`EV/Revenue (LTM)`	float or null	Enterprise value to last-twelve-months revenue multiple.
`EV/EBITDA (LTM)`	float or null	Enterprise value to LTM EBITDA multiple.
`P/E (LTM)`	float or null	Price-to-earnings ratio on LTM basis.

M&A history

Field	Type	Description
`Acquisitions`	string or null	Comma-separated list of past acquisitions with year (e.g. `"Hutchinson Plumbing (2020), Casteel (2017)"`).
`Investments`	string or null	Notable investments made by the peer. May be null.

AI similarity scoring

Field	Type	Description
`Overall Score`	float	Similarity score (1–10) measuring how closely the peer matches the seed company on product, customer segment, business model, and geography. Higher = closer match.
`Commentary`	string	AI-written paragraph explaining the similarity to the seed company — calling out specific product overlaps, geographic differences, scale differences, and any unique offerings of the peer.

The Competitor List API focuses on similarity to a seed company, so its AI scoring is a single composite Overall Score plus a Commentary paragraph. This is intentionally simpler than Buyer or Target Screening, which return multiple sub-scores (feasibility, precedent, synergy) because they evaluate a deal, not just similarity. Read the Commentary carefully — it’s where the AI explains why a peer was scored as such.

6. Examples

Building a peer set for a private company

Find U.S.-based private companies similar to Del-Air, focused on residential home services. Filter to peers of comparable scale and rank by similarity.

curl --location 'https://api.wokelo.ai/api/enterprise/company-peers/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "company": "del-air",
    "parameters": {
      "detailed_query": "Residential home services companies",
      "geography": ["USA"],
      "company_type": "private"
    }
  }'

import requests, time

HEADERS = {
    "Authorization": "Bearer <YOUR_API_TOKEN>",
    "Content-Type": "application/json"
}

# Submit
job = requests.post(
    "https://api.wokelo.ai/api/enterprise/company-peers/enrich/",
    headers=HEADERS,
    json={
        "company": "del-air",
        "parameters": {
            "detailed_query": "Residential home services companies",
            "geography": ["USA"],
            "company_type": "private"
        }
    }
).json()

request_id = job["request_id"]

# Poll
while True:
    s = requests.get(
        f"https://api.wokelo.ai/api/enterprise/request/{request_id}/status/",
        headers=HEADERS
    ).json()["status"]
    if s == "COMPLETED": break
    time.sleep(5)

# Retrieve and rank by similarity
peers = requests.get(
    f"https://api.wokelo.ai/api/enterprise/request/{request_id}/result/",
    headers=HEADERS
).json()["result"]

close_peers = sorted(
    [p for p in peers if p.get("Overall Score", 0) >= 8],
    key=lambda x: x["Overall Score"],
    reverse=True
)

for p in close_peers:
    print(f"{p['Name']} ({p['HQ City']}) — Score: {p['Overall Score']}")
    print(f"  {p.get('Product Category', 'n/a')}")

Sample response (excerpt):

{
  "request_id": "450c0d25-c83b-4fc7-8713-f96b63db7843",
  "status": "COMPLETED",
  "result": [
    {
      "Permalink": "horizon-services",
      "Name": "Horizon Services",
      "Website": "horizonservices.com",
      "HQ City": "Wilmington",
      "HQ Country": "United States",
      "Founded": "1987",
      "Type": "Private",
      "Operating Status": "Acquired",
      "Product Category": "Residential Plumbing HVAC Services",
      "Core Offering": "Horizon Services provides plumbing, heating, and air conditioning services, including installation, maintenance, and repair, primarily for residential customers.",
      "Employees (Crunchbase)": "501-1000",
      "Employees (LinkedIn)": 446,
      "Acquisitions": "Hutchinson Plumbing Heating Cooling (2020), Casteel (2017), Gold Medal Service (2017)",
      "Overall Score": 9.0,
      "Commentary": "Horizon Services primarily delivers residential plumbing, heating, and air conditioning services, including installation, maintenance, and repair, plus drain cleaning and sewer repair. This maps closely to Del-Air's HVAC and home services model with strong evidence of direct residential service operations and regional leadership in that category."
    },
    {
      "Permalink": "the-wrench-group",
      "Name": "Wrench Group",
      "Website": "wrenchgroup.com",
      "HQ City": "Marietta",
      "HQ Country": "United States",
      "Founded": "2015",
      "Type": "Private",
      "Operating Status": "Acquired",
      "Product Category": "Home Repair Maintenance Services",
      "Funding Stage": "Debt-Funded",
      "Total Funding": 1300000000.0,
      "Key Investors": ["Oak Hill Capital Partners", "Crescent Capital Group", "TSG Consumer Partners", "Blue Owl"],
      "Acquisitions": "Lindstrom Air Conditioning & Plumbing (2024), Superior Service (2022), Nexgen (2022), Buckeye Heating & Cooling (2021), Williams Comfort Air (2021)",
      "Overall Score": 9.0,
      "Commentary": "Wrench Group primarily provides residential home repair, replacement, and maintenance services specializing in HVAC, plumbing, and electrical, including heating and air conditioning installation, repair, and maintenance. Its multi-brand, direct-to-consumer model and emergency/service-center approach align closely with Del-Air's core residential HVAC and related home services across major U.S. metros."
    }
  ]
}

Competitive landscape for a public software company

Build a peer set for a public SaaS company to support valuation work or competitive positioning. Restrict to public peers and use revenue filters to find comparables of similar scale.

import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/company-peers/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "company": "crowdstrike",
        "parameters": {
            "detailed_query": "Public cybersecurity platforms covering endpoint protection, XDR, and cloud security",
            "company_type": "public",
            "revenue": {"from": 200000000}
        }
    }
)
print(response.json()["request_id"])

Roll-up sourcing for a PE platform

Find regional competitors and add-on targets similar to a platform company. Narrow the detailed_query to the platform’s core service lines and use geography, employee_count, and total_funding filters to find absorbable players.

import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/company-peers/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "company": "del-air",
        "parameters": {
            "detailed_query": "Regional residential HVAC and plumbing contractors suitable for roll-up consolidation",
            "geography": ["USA"],
            "company_type": "private",
            "employee_count": ["51-100", "101-250", "251-500"],
            "total_funding": {"to": 50000000}
        }
    }
)
print(response.json()["request_id"])

Disambiguating a multi-product seed with `detailed_query`

When the seed company operates across multiple product lines, use detailed_query to focus the peer set on a specific segment. Without this, the API returns peers matching the broadest interpretation of the seed.

# Without detailed_query: returns broad set of "Amazon-like" companies
# With detailed_query: returns peers specifically in cloud infrastructure
import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/company-peers/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "company": "amazon",
        "parameters": {
            "detailed_query": "Public cloud infrastructure and platform providers (IaaS/PaaS), not retail or marketplaces",
            "sample_companies": ["microsoft-azure", "google-cloud"],
            "company_type": "public"
        }
    }
)
print(response.json()["request_id"])

7. Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with a detail or message field.

Status	Meaning	Cause & Resolution
`200 OK` / `202 Accepted`	Success	Job submitted (`202`) or result retrieved (`200`) successfully.
`400 Bad Request`	Invalid parameters	A required field is missing or a parameter value is invalid — e.g. missing `parameters` object, unrecognised `funding_stage`, or malformed `founded_year` object. Check the `detail` field.
`401 Unauthorized`	Auth failed	The `Authorization` header is missing, malformed, or contains an invalid token. Verify your key in Settings → API Keys.
`403 Forbidden`	Insufficient access	Your plan does not include access to this endpoint. Contact support@wokelo.ai to review your plan.
`404 Not Found`	Resource not found	The seed `company` permalink could not be resolved, a `sample_companies` permalink is invalid, or the `request_id` does not exist. Use the Company Search API to verify permalinks.
`429 Too Many Requests`	Rate limit exceeded	Implement exponential back-off. The response includes a `Retry-After` header.
`500 Internal Server Error`	Server error	Retry after a brief delay. If the issue persists, contact support@wokelo.ai with your `request_id`.

Error response example:

{
  "status": "error",
  "detail": "Company permalink 'unknown-co' could not be resolved."
}

Job failure handling:

import requests, time

def poll_until_done(request_id, headers, interval=5, timeout=600):
    elapsed = 0
    while elapsed < timeout:
        resp = requests.get(
            f"https://api.wokelo.ai/api/enterprise/request/{request_id}/status/",
            headers=headers
        ).json()
        status = resp["status"]
        if status == "COMPLETED":
            return True
        elif status == "FAILED":
            raise Exception(f"Job {request_id} failed: {resp.get('detail', 'unknown error')}")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError(f"Job {request_id} did not complete within {timeout}s")

8. Best Practices

Use detailed_query to focus multi-product seed companies If the seed company spans multiple product lines or segments (e.g. Amazon, Microsoft, Salesforce), the peer set can drift toward whichever segment the AI infers as dominant. Use detailed_query to lock the run to a specific segment — for example, “Public cloud infrastructure and platform providers, not retail” for Amazon, or “CRM and customer data platforms, excluding analytics tools” for Salesforce. For single-product seed companies, detailed_query is often unnecessary. Anchor the peer set with sample_companies when the seed is niche or ambiguous For niche businesses, regional players, or companies whose public profile is thin, supply 2–4 representative permalinks in sample_companies to bias the search toward the right flavour of competitor. Use the Company Search API to resolve company names to permalinks. Always include the full parameters object Even when you don’t want to filter on a field, the API expects the parameters object to be present. Pass empty values ("", [], {}) for unused filters. Omitting parameters entirely returns a 400 Bad Request. Tier peers by Overall Score before review Sort results descending by Overall Score and segment into tiers (e.g. 9–10: Direct competitors, 7–8: Close peers, 5–6: Adjacent, below 5: Tangential) for efficient triage. The Commentary paragraph then explains why each peer was scored — calling out specific product overlaps, geographic differences, or scale differences worth knowing before downstream work. Read the Commentary to validate the peer set The Commentary is the most diagnostic signal in the response. A peer with a high Overall Score but a commentary noting “narrower geographic focus” or “broader product scope” is still useful context for benchmarking or competitive positioning. Use the commentary to decide which peers to include in a final comparable set. Combine filters thoughtfully for valuation comparables When building a comparable set for valuation, layer company_type, revenue, ebitda, and ev_ebitda filters to find peers at similar financial scale. For public-company comparables, set company_type: "public" so financial fields are reliably populated. For private-company peers, use funding_stage, total_funding, and employee_count instead since financial fields will mostly be null. Compare against Market Map when defining a market If your seed company is a clear category-defining player and you want to map the full category, run Competitor List first to get the strongest direct peers, then run Market Map with the category as the topic to capture earlier-stage and tangential players Competitor List may miss. The two endpoints are complementary. Iterate the query — treat the first run as a diagnostic Review the top 20 peers and their commentaries from the first run, then refine detailed_query, swap or add sample_companies, or tighten filters and re-run. Two or three iterations typically produce a substantially cleaner peer set than a single pass. Store the request_id for reproducibility Each peer set is a snapshot at a point in time. Store the request_id alongside the seed company, parameters, and run date so you can re-retrieve the same result set later, compare runs over time as the market evolves, or audit which peer set was used for a given valuation or competitive memo.

Market Map

Discover and map all companies competing in a specific market or product category — start from a topic instead of a single seed company.

Target Screening

Identify and score acquisition targets for a defined acquirer with deal-fit scoring.

Buyer Screening

Identify and score potential acquirers for a target company.

Peer Comparison

Run side-by-side financial and operational comparisons across a defined peer set.

Company Deep Intelligence

Generate deep AI intelligence on any peer — business model, financials, strategy, and M&A history.

Company Instant Enrichment

Synchronously enrich firmographic and financial data for any peer in the result set.

​1. Overview

​2. Quick Start

​3. Authentication

​4. Request Reference

​5. Response

​Job submission response

​Completed result response

​Peer object fields

​6. Examples

​Building a peer set for a private company

​Competitive landscape for a public software company

​Roll-up sourcing for a PE platform

​Disambiguating a multi-product seed with detailed_query

​7. Error Handling

​8. Best Practices

​9. Related APIs

Market Map

Target Screening

Buyer Screening

Peer Comparison

Company Deep Intelligence

Company Instant Enrichment

1. Overview

2. Quick Start

3. Authentication

4. Request Reference

5. Response

Job submission response

Completed result response

Peer object fields

6. Examples

Building a peer set for a private company

Competitive landscape for a public software company

Roll-up sourcing for a PE platform

Disambiguating a multi-product seed with `detailed_query`

7. Error Handling

8. Best Practices

9. Related APIs