Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wokelo.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. Overview

The Market Map API generates a long list of companies operating in a defined market category, enriched with structured firmographic, funding, and financial data. Given a market topic (e.g. “AI-powered CRM software”) and a set of optional filters, Wokelo’s AI pipeline searches its coverage universe of 20M+ companies, evaluates each candidate against the market thesis, and returns a ranked list with AI-generated relevance 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 company 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)
  • AI fit scoring — an Overall Score (1–10) with a written commentary explaining each company’s relevance to the queried market thesis
Common use cases:
  • Deal sourcing for private equity & venture capital — Build a comprehensive, scored target universe within a specific vertical or thesis
  • Corporate strategy & M&A — Map the competitive landscape for a new market entry, partnership scan, or build-vs-buy analysis
  • Investment banking — Populate market landscape slides for pitch books, CIMs, or sector reports
  • Market research & consulting — Generate an exhaustive set of vendors in a category for benchmarking or category analysis
  • Sales & GTM intelligence — Identify all companies in an adjacent or competing category for partner mapping or competitive battlecards
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/market-map/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "AI-powered CRM software",
    "parameters": {
      "detailed_query": "B2B CRM tools leveraging AI for sales automation",
      "keywords": ["AI", "CRM", "sales automation"],
      "sample_companies": ["salesforce", "hubspot"],
      "geography": ["USA"],
      "company_type": "private"
    }
  }'
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>"}
)
companies = result_resp.json()["result"]
for c in companies:
    print(c["Name"], "—", c.get("Product Category"), "— Score:", c.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/market-map/enrich/
The request body is JSON. Only topic is required; all parameters fields are optional refinements. Each filter that you add narrows the universe — the more precise your filters, the more focused and relevant the results.
ParameterTypeRequiredDescription
topicstringRequiredThe market or product category to map (e.g. "AI-powered CRM software", "Field service management software for HVAC contractors"). Should be specific enough to define a clear category.
parameters.detailed_querystringOptionalA natural-language description of the market scope, ideal company profile, or thesis. The single highest-impact parameter for result quality. Example: "B2B CRM tools leveraging AI for sales automation in mid-market and enterprise segments".
parameters.keywordsstring[]OptionalKeywords used to identify and filter relevant companies. Use 3–6 product or category terms. Example: ["AI", "CRM", "sales automation"].
parameters.sample_companiesstring[]OptionalPermalinks (e.g. "salesforce") or full URLs of representative companies to anchor the search. Use the Company Search API to resolve a permalink. Strongly recommended for niche markets.
parameters.geographystring[]OptionalGeographic scope as ISO country codes (e.g. ["USA", "GBR"]). Defaults to global if omitted.
parameters.company_typestringOptionalOwnership type filter. Accepted values: "private", "public", "all". Defaults to "all".
parameters.employee_countstring[]OptionalHeadcount 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_yearobjectOptionalFilter by founding year. Accepts { "from": 2015 }, { "to": 2022 }, or both.
parameters.funding_stagestring[]OptionalFilter 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_fundingobjectOptionalFilter by total funding raised in USD. Accepts { "from": 5000000 }, { "to": 100000000 }, or both.
parameters.last_funding_roundobjectOptionalFilter by last funding round size. Accepts from and/or to values.
parameters.revenueobjectOptionalFilter by annual revenue (USD). Accepts from and/or to values. Most useful when combined with company_type: "public".
parameters.ebitdaobjectOptionalFilter by EBITDA (USD). Accepts from and/or to values.
parameters.net_incomeobjectOptionalFilter by net income (USD). Accepts from and/or to values.
parameters.ev_ebitdaobjectOptionalFilter by EV/EBITDA multiple. Accepts from and/or to values.
Full request example:
curl --location 'https://api.wokelo.ai/api/enterprise/market-map/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "AI-powered CRM software",
    "parameters": {
      "detailed_query": "B2B CRM tools leveraging AI for sales automation",
      "keywords": ["AI", "CRM", "sales automation"],
      "sample_companies": ["salesforce", "hubspot"],
      "geography": ["USA"],
      "company_type": "private",
      "employee_count": ["11-50", "51-100"],
      "founded_year": { "from": 2015 },
      "funding_stage": ["Series A", "Series B"],
      "total_funding": { "from": 5000000 }
    }
  }'

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": "ed2ce223-3bd2-4a08-855f-79751bf1bd92",
  "status": "PENDING"
}
FieldTypeDescription
request_idstringUnique identifier for this job. Use it to poll status and retrieve results.
statusstringInitial job state. One of "PENDING", "PROCESSING", "COMPLETED", "FAILED".

Completed result response

Once status is "COMPLETED", the result contains a result array of company objects.
{
  "request_id": "ed2ce223-3bd2-4a08-855f-79751bf1bd92",
  "status": "COMPLETED",
  "result": [ ...company objects... ]
}

Company object fields

Each object in the result array contains the following fields: Identity & firmographics
FieldTypeDescription
PermalinkstringWokelo company identifier (e.g. "esub-construction-software"). Use this with other Wokelo APIs.
NamestringDisplay name of the company.
WebsitestringPrimary domain (e.g. "esub.com").
HQ CitystringHeadquarters city.
HQ CountrystringHeadquarters country.
HQ ContinentstringHeadquarters continent.
FoundedstringYear the company was founded.
TypestringOwnership type: "Public" or "Private".
Operating StatusstringCurrent operational status (e.g. "Operating", "Acquired", "IPO").
Product & business
FieldTypeDescription
Product CategorystringHigh-level category describing the company’s primary product (e.g. "Construction Project Management Software").
Core OfferingstringAI-generated paragraph describing the company’s core business and product.
Product CatalogstringComma-separated list of key products and services offered.
People & funding
FieldTypeDescription
Employees (Crunchbase)stringEmployee count band from Crunchbase (e.g. "51-100").
Employees (LinkedIn)integer or emptyEmployee count from LinkedIn. May be empty.
Funding StagestringMost recent funding stage (e.g. "Series B"). May be empty for public or bootstrapped companies.
Total Fundingfloat or emptyTotal disclosed funding raised in USD.
Last Funding DatestringDate of the most recent funding round (YYYY-MM-DD).
Key Investorsstring[]Array of notable investors.
Financials (primarily for public companies)
FieldTypeDescription
Revenuefloat or emptyAnnual revenue in USD.
TickerstringExchange and ticker symbol (e.g. "NASDAQ:CRM").
EBITDAfloat or emptyEarnings before interest, taxes, depreciation, and amortisation.
Net Incomefloat or emptyNet income in USD.
EBITDA Margin (%)float or emptyEBITDA as a percentage of revenue.
Net Income Margin (%)float or emptyNet income as a percentage of revenue.
EPS Dilutedfloat or emptyDiluted earnings per share.
ROA (%)float or emptyReturn on assets.
Unlevered FCFfloat or emptyUnlevered free cash flow in USD.
D/Efloat or emptyDebt-to-equity ratio.
Market Capfloat or emptyMarket capitalisation in USD.
Enterprise Valuefloat or emptyEnterprise value in USD.
EV/Revenue (LTM)float or emptyEnterprise value to last-twelve-months revenue multiple.
EV/EBITDA (LTM)float or emptyEnterprise value to LTM EBITDA multiple.
P/E (LTM)float or emptyPrice-to-earnings ratio on LTM basis.
M&A history
FieldTypeDescription
AcquisitionsstringComma-separated list of past acquisitions with year.
InvestmentsstringNotable investments made by the company. May be empty.
AI scoring
FieldTypeDescription
Overall ScorefloatComposite relevance score (1–10) measuring how well the company fits the queried market thesis. Higher is a stronger fit.
CommentarystringAI-written paragraph explaining why this company does or does not fit the market thesis — calls out specific product features, target customers, and geographic alignment.
Private companies typically return populated funding fields and empty financial fields. Public companies return populated financial fields and typically empty funding-stage fields. Read the Commentary carefully — it explains why the AI included each company and is the most useful signal for triaging the result set.

6. Examples

Vertical SaaS deal sourcing

Find all private field service management software companies serving commercial HVAC and electrical contractors in the United States — 51 to 250 employees, Series A or B, founded after 2013.
curl --location 'https://api.wokelo.ai/api/enterprise/market-map/enrich/' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "Field service management software for commercial HVAC and electrical contractors",
    "parameters": {
      "detailed_query": "Private field service management software companies serving commercial HVAC and electrical contractors in the United States with scheduling, dispatch, mobile work orders, and billing",
      "geography": ["USA"],
      "company_type": "private",
      "employee_count": ["51-100", "101-250"],
      "founded_year": { "from": 2013 },
      "funding_stage": ["Series A", "Series B"]
    }
  }'
Sample response (excerpt):
{
  "request_id": "a57a9100-e7e1-4c6c-9b29-cdd064516ba7",
  "status": "COMPLETED",
  "result": [
    {
      "Permalink": "esub-construction-software",
      "Name": "eSUB Construction Software",
      "Website": "esub.com",
      "HQ City": "San Diego",
      "HQ Country": "United States",
      "Founded": "2008",
      "Type": "Private",
      "Operating Status": "Operating",
      "Product Category": "Construction Project Management Software",
      "Core Offering": "ESUB Construction Software provides cloud-based project management solutions specifically designed for subcontractors in the construction industry...",
      "Employees (Crunchbase)": "51-100",
      "Funding Stage": "Series B",
      "Total Funding": 22000000.0,
      "Last Funding Date": "2023-05-01",
      "Key Investors": ["Autodesk", "Revolution", "Catalyst Investors"],
      "Overall Score": 7.0,
      "Commentary": "eSUB Construction Software provides cloud-based project management and document control for commercial subcontractors, with mobile field reporting, timecards, RFIs, submittals, and change orders. The platform explicitly serves electrical and HVAC contractors in the United States, making it a strong direct fit for field service management workflows."
    },
    {
      "Permalink": "kloudgin",
      "Name": "KloudGin",
      "Website": "kloudgin.com",
      "HQ City": "Sunnyvale",
      "HQ Country": "United States",
      "Founded": "2014",
      "Type": "Private",
      "Product Category": "Field Service Asset Management Software",
      "Employees (Crunchbase)": "101-250",
      "Funding Stage": "Series A",
      "Total Funding": 8200000.0,
      "Overall Score": 7.0,
      "Commentary": "KloudGin provides cloud-based field service management software and asset management, automating work management processes with scheduling, dispatch, mobile work orders, and billing..."
    }
  ]
}

Public-market competitive landscape

Map the public companies in a category for a competitive landscape slide in a sector report. Use company_type: "public" and revenue filters to narrow to scaled players.
import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/market-map/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "topic": "Cybersecurity endpoint protection platforms",
        "parameters": {
            "detailed_query": "Public cybersecurity vendors offering endpoint detection and response (EDR), XDR, and endpoint protection at enterprise scale",
            "keywords": ["EDR", "XDR", "endpoint protection", "cybersecurity"],
            "sample_companies": ["crowdstrike", "sentinelone"],
            "company_type": "public",
            "revenue": {"from": 100000000}
        }
    }
)
print(response.json()["request_id"])

Anchored search for a niche market

When the market is niche or jargon-heavy, anchor the search with 2–4 well-known players using sample_companies. This dramatically improves precision over keyword-only search.
import requests

response = requests.post(
    "https://api.wokelo.ai/api/enterprise/market-map/enrich/",
    headers={
        "Authorization": "Bearer <YOUR_API_TOKEN>",
        "Content-Type": "application/json"
    },
    json={
        "topic": "AI-native legal contract review tools",
        "parameters": {
            "detailed_query": "AI-first contract review and CLM platforms targeting in-house legal teams, with LLM-based clause extraction and redlining",
            "sample_companies": ["ironclad", "spellbook", "evisort"],
            "company_type": "private",
            "founded_year": {"from": 2018}
        }
    }
)
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.
StatusMeaningCause & Resolution
200 OK / 202 AcceptedSuccessJob submitted (202) or result retrieved (200) successfully.
400 Bad RequestInvalid parametersA required field is missing or a parameter value is invalid — e.g. unrecognised employee_count band, malformed founded_year object, or invalid ISO country code. Check the detail field.
401 UnauthorizedAuth failedThe Authorization header is missing, malformed, or contains an invalid token. Verify your key in Settings → API Keys.
403 ForbiddenInsufficient accessYour plan does not include access to this endpoint. Contact support@wokelo.ai to review your plan.
404 Not FoundResource not foundA sample_companies permalink could not be resolved, or the request_id does not exist. Use the Company Search API to verify permalinks.
429 Too Many RequestsRate limit exceededImplement exponential back-off. The response includes a Retry-After header.
500 Internal Server ErrorServer errorRetry after a brief delay. If the issue persists, contact support@wokelo.ai with your request_id.
Error response example:
{
  "status": "error",
  "detail": "Invalid value for parameter 'employee_count': '50-100' is not a supported band."
}
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

Write a specific detailed_query — this matters most The detailed_query is by far the highest-leverage parameter in this API. A vague query like "CRM software" will return a broad and noisy universe; a specific query naming the customer segment, product capabilities, distribution model, and use case will return a tight, relevant set. For example:
“B2B CRM tools leveraging AI for sales automation in mid-market and enterprise segments with native pipeline forecasting and email-engagement scoring”
is far stronger than:
“AI CRM”
Anchor niche or jargon-heavy markets with sample_companies For specialised verticals where the AI cannot fully infer the market from a topic and keywords alone, supply 2–4 representative permalinks in sample_companies. This dramatically improves precision. Use the Company Search API to resolve company names to permalinks. Combine multiple filters to bound the universe Layering geography, company_type, employee_count, founded_year, and funding_stage produces a much tighter, more usable list than a single filter. For deal sourcing in particular, combining funding_stage + employee_count + founded_year is the standard recipe for finding scale-up-stage targets. Sort and tier by Overall Score before review The Overall Score is Wokelo’s composite fit metric for the queried market. Sort results descending by Overall Score and segment into tiers (e.g. 8–10: Strong fit, 5–7: Adjacent, below 5: Tangential) to triage efficiently. The Commentary field then explains why the AI scored each company that way. Read the Commentary to validate inclusions and exclusions The Commentary field is the most diagnostic signal in the response. It will often explain why a high-profile company was or was not a strong fit — for example, a marketplace adjacent to your category may be returned with a low score and a commentary noting that it is not a direct match. Use this both to triage and to refine your next query. Use company_type to align with financial filters Revenue, EBITDA, and EV multiple filters are most reliable for public companies. If you want to filter on revenue or ev_ebitda, set company_type: "public". For private-company filtering, use funding_stage, total_funding, and employee_count instead. Store the request_id for reproducibility Each market map is a snapshot at a point in time. Store the request_id alongside the topic, 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 company list was used for a given investment thesis or report. Iterate the query — don’t expect one-shot perfection Treat the first run as a diagnostic. Review the top 20 results and their commentaries, then refine detailed_query, swap sample_companies, or tighten filters and re-run. Two or three iterations typically produce a substantially better universe than a single pass.

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.

Competitor List

Generate a structured list of direct and indirect competitors for a specific company.

Company Deep Intelligence

Generate deep AI intelligence on any company in the market map — business model, financials, strategy.

Company Instant Enrichment

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

Industry Deep Intelligence

Generate a deep intelligence report on the industry behind the market map.