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 arequest_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
- 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 job3. Authentication
All requests must include a Bearer token in theAuthorization HTTP header. No other authentication method is supported.
4. Request Reference
Endpointtopic 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
topic | string | Required | The 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_query | string | Optional | A 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.keywords | string[] | Optional | Keywords used to identify and filter relevant companies. Use 3–6 product or category terms. Example: ["AI", "CRM", "sales automation"]. |
parameters.sample_companies | string[] | Optional | Permalinks (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.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": 2015 }, { "to": 2022 }, 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": 5000000 }, { "to": 100000000 }, or both. |
parameters.last_funding_round | object | Optional | Filter by last funding round size. Accepts from and/or to values. |
parameters.revenue | object | Optional | Filter by annual revenue (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. |
5. Response
Job submission response
When you submit the job, you receive a response immediately with arequest_id and an initial status.
| 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
Oncestatus is "COMPLETED", the result contains a result array of company objects.
Company object fields
Each object in theresult array contains the following fields:
Identity & firmographics
| Field | Type | Description |
|---|---|---|
Permalink | string | Wokelo company identifier (e.g. "esub-construction-software"). Use this with other Wokelo APIs. |
Name | string | Display name of the company. |
Website | string | Primary domain (e.g. "esub.com"). |
HQ City | string | Headquarters city. |
HQ Country | string | Headquarters country. |
HQ Continent | string | Headquarters continent. |
Founded | string | Year the company was founded. |
Type | string | Ownership type: "Public" or "Private". |
Operating Status | string | Current operational status (e.g. "Operating", "Acquired", "IPO"). |
| Field | Type | Description |
|---|---|---|
Product Category | string | High-level category describing the company’s primary product (e.g. "Construction Project Management Software"). |
Core Offering | string | AI-generated paragraph describing the company’s core business and product. |
Product Catalog | string | Comma-separated list of key products and services offered. |
| Field | Type | Description |
|---|---|---|
Employees (Crunchbase) | string | Employee count band from Crunchbase (e.g. "51-100"). |
Employees (LinkedIn) | integer or empty | Employee count from LinkedIn. May be empty. |
Funding Stage | string | Most recent funding stage (e.g. "Series B"). May be empty for public or bootstrapped companies. |
Total Funding | float or empty | Total disclosed funding raised in USD. |
Last Funding Date | string | Date of the most recent funding round (YYYY-MM-DD). |
Key Investors | string[] | Array of notable investors. |
| Field | Type | Description |
|---|---|---|
Revenue | float or empty | Annual revenue in USD. |
Ticker | string | Exchange and ticker symbol (e.g. "NASDAQ:CRM"). |
EBITDA | float or empty | Earnings before interest, taxes, depreciation, and amortisation. |
Net Income | float or empty | Net income in USD. |
EBITDA Margin (%) | float or empty | EBITDA as a percentage of revenue. |
Net Income Margin (%) | float or empty | Net income as a percentage of revenue. |
EPS Diluted | float or empty | Diluted earnings per share. |
ROA (%) | float or empty | Return on assets. |
Unlevered FCF | float or empty | Unlevered free cash flow in USD. |
D/E | float or empty | Debt-to-equity ratio. |
Market Cap | float or empty | Market capitalisation in USD. |
Enterprise Value | float or empty | Enterprise value in USD. |
EV/Revenue (LTM) | float or empty | Enterprise value to last-twelve-months revenue multiple. |
EV/EBITDA (LTM) | float or empty | Enterprise value to LTM EBITDA multiple. |
P/E (LTM) | float or empty | Price-to-earnings ratio on LTM basis. |
| Field | Type | Description |
|---|---|---|
Acquisitions | string | Comma-separated list of past acquisitions with year. |
Investments | string | Notable investments made by the company. May be empty. |
| Field | Type | Description |
|---|---|---|
Overall Score | float | Composite relevance score (1–10) measuring how well the company fits the queried market thesis. Higher is a stronger fit. |
Commentary | string | AI-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.Public-market competitive landscape
Map the public companies in a category for a competitive landscape slide in a sector report. Usecompany_type: "public" and revenue filters to narrow to scaled players.
Anchored search for a niche market
When the market is niche or jargon-heavy, anchor the search with 2–4 well-known players usingsample_companies. This dramatically improves precision over keyword-only search.
7. Error Handling
The API uses standard HTTP status codes. All error responses include a JSON body with adetail 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. unrecognised employee_count band, malformed founded_year object, or invalid ISO country code. 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 | A 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 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. |
8. Best Practices
Write a specificdetailed_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.
9. Related APIs
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.