Skip to main content

1. Overview

The Company Research API generates an in-depth intelligence report on any company, covering firmographics, financial signals, executive commentary, product portfolio, product launches, and M&A history. The report is fully source-cited and delivered as structured JSON or as a formatted document (PDF, DOCX, or PPT). This is an asynchronous POST API — submitting a request returns a report_id immediately. You then poll for completion using the Report Status endpoint and retrieve the finished report using the Download Report endpoint. The three-step workflow:
The completed report is structured into five major sections, each returned as a named key in the JSON output:
  • Quick Snapshot — firmographic card with financials, headcount, funding stage, HQ, and product summary
  • Executive Summary — multi-paragraph narrative covering strategy, recent developments, competitive dynamics, and key capabilities; fully source-cited
  • Key Insights — 8–10 analyst-style insight cards, each with a headline metric, supporting data paragraph, multi-point commentary, and source citations
  • Product Insights — product overview narrative, categorised product/service list, product launch timeline with summaries, and a screenshot
  • Transaction Highlights — M&A and investment map as structured data, plus a detailed acquisition timeline with deal amounts and strategic commentary
Common use cases:
  • Pre-meeting company briefings — generate a sourced, structured brief on any target or prospect before a call, in minutes rather than hours
  • Deal screening packages — run Company Research on a shortlist of acquisition targets and export as PDF or PPT for IC review
  • Portfolio company monitoring — schedule quarterly runs on portfolio companies and diff the Key Insights across periods to track strategic shifts
  • Competitive intelligence — run against a set of competitors and compare product portfolios and M&A timelines side by side
  • CRM enrichment — ingest the JSON output and push firmographic and financial fields into Salesforce, HubSpot, or DealCloud records automatically
  • Custom report augmentation — supply custom_files to layer proprietary internal data (CIM, management presentation, diligence notes) on top of Wokelo’s synthesis
This API is asynchronous. The initial POST returns a report_id only — not the report content. Report generation typically completes in 2–5 minutes. See How Async APIs work for a full explanation of the polling lifecycle.

2. Quick Start

Step 1 — Submit the report request
Step 2 — Poll for completion
Step 3 — Download the report

3. Authentication

All requests must include a Bearer token in the Authorization HTTP header.
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
All parameters are passed as JSON in the request body.
Either permalink or website is required — at least one must be provided. If both are supplied, permalink takes precedence. If you cannot find a company’s permalink via Company Search, pass the full company website URL instead.
Full request example:

5. Response

Submission response

The initial POST returns immediately with a single field:

Report status response

Poll GET /api/assets/get_notebook_status/?report_id={report_id} until the status field is "Completed".

Downloaded report structure

When you call Download Report with "file_type": "json", the response is a deeply nested JSON object. Each top-level key is a named report section. The five sections produced by Company Research are: Quick Snapshot Contains a quick_snapshot object with two sub-objects:
  • company_firmographics — organisation name, logo, dashboard URL, and a details object covering: industry, founded_year, website, hq, operating_status, company_type, employees_in_crunchbase, employees_in_linkedin, last_funding_round, ticker, and a financials object with revenue, ebitda, pat, and market_cap (each with currency, value, and period fields)
  • product_detailsproduct_category (short label) and summary (one-paragraph product description)
Executive Summary Contains a summary field with a full markdown-formatted multi-section narrative (Overview, Strategic Positioning, Recent Developments, Competitive Dynamics, Key Capabilities), plus a source array of citation objects, each with id, title, url, publisher, and date. Key Insights Contains a key_insights array of 8–10 insight card objects. Each card has:
  • insight — object with title (bold headline with key metric), paragraph (supporting data sentence), and sources array
  • commentary — array of 2–3 commentary paragraph objects, each with paragraph (analyst interpretation) and sources array
Product Insights Contains two sub-sections:
  • Product and servicesproduct_overview (summary narrative + screenshot_url) and products_and_services (array of product area objects, each with product_area label, details array of {title, summary} objects, and sources citation range)
  • Product launches and initiativesreleased_products array of launch objects, each with date, initiative, summary (bullet array), and sources array of {url, title, publisher, publishedDate} objects; and future_announcements array
Transaction Highlights Contains two sub-sections:
  • M&A and Investments mapm_andn_a_map with a charts object containing m_and_a_investment_map, which has a data array of deal objects (year, company_name, product_category, headquarters, permalink, website, type as "mna" or "investment", plus parent company fields), a source attribution string, and a url to the chart image
  • M&A Strategyacquisitions with m_and_a_timeline array of detailed acquisition objects, each with a nested company card (firmographics + description), acquisition_date, acquisition_amount (numeric USD or empty string), and commentary
The acquisition_amount field is a raw numeric USD value (e.g. 1900000000.0 for $1.9B) or an empty string when the deal value was not publicly disclosed. Always check for empty string before converting to currency.

Download format options

The file_type parameter in the Download Report request controls the output format.

6. Examples

The most common pattern: look up the permalink, submit, poll, and download JSON.
Sample submission response:
When the company’s permalink is unknown or unavailable, pass the full website URL.
Use the Company Search API to find a company’s permalink by name, then pass it to Company Research.

Batch research on a watchlist

Submit Company Research for multiple companies concurrently, then collect all reports once completed.

Research with a custom file (CIM or management deck)

Upload a proprietary file and attach it to the report so Wokelo synthesises it alongside its own research.

Extracting specific sections from the JSON report

Work with individual sections of the downloaded JSON for targeted downstream processing.

Exporting a PPT for IC review


7. Error Handling

The API uses standard HTTP status codes. The submission endpoint returns errors synchronously; processing errors appear as a "Failed" status when polling. Handling a "Failed" report status:
Retry with exponential back-off on submission:

8. Best Practices

Always use permalink over website when available Permalinks resolve faster and more reliably than website URLs, particularly for companies with complex domain structures or redirects. Use the Company Search API to resolve a company name to its permalink before submitting:
workflow must always be "company_primer" — this field is not optional The /api/workflow_manager/start/ endpoint is shared across all Workflow APIs (Company Research, Industry Research, Peer Comparison, Custom). The workflow parameter is what distinguishes between them. For Company Research, it must be exactly "company_primer". Omitting it or misspelling it returns a 400 error. Store report_id immediately and durably The submission response contains only report_id. If this value is lost before the report is downloaded, there is no API endpoint to list or retrieve past report_id values. Store it to a database, log, or queue entry as soon as the submission response is received. Use 15–20 second polling intervals — not tight loops Reports typically complete in 2–5 minutes. Polling more frequently than every 15 seconds wastes rate limit budget without meaningfully reducing latency. Use a back-off strategy for batch workloads:
Provide industry to improve report framing for niche companies Wokelo auto-detects industry from its knowledge base, but for newer companies, international companies, or firms in niche verticals, providing the industry string directly improves the accuracy of competitive framing and peer positioning within the Executive Summary and Key Insights:
Use custom_files to layer internal data on public synthesis The custom_files parameter is the most differentiated capability of this API for investment workflows. Uploading a CIM, management presentation, or prior diligence memo alongside the request causes Wokelo to synthesise both the public web research and your internal documents into a unified report. Upload files via the File Upload API first, then reference the returned fileName in your request. Parse acquisition_amount defensively — it can be an empty string or a float The acquisition_amount field in the M&A timeline is either a numeric float (raw USD) or an empty string "" for undisclosed deals. Never assume it is numeric:
Use "json" output for pipelines; "ppt" or "pdf" for human deliverables The JSON output contains every field, source citation, and structured data object. Use it for any downstream processing — CRM ingestion, comparison tools, alerting. The PDF, DOCX, and PPT outputs are rendered for human consumption and strip much of the structured metadata. Request only the format you need — a single report_id supports all four formats.

Company Instant Enrichment

Synchronous firmographic enrichment — returns structured company data immediately without a report generation step.

Company Deep Intelligence

Deeper async intelligence on strategy, financials, and competitive positioning — more granular than Company Research.

Industry Research

Run the same async workflow pattern against an industry or sector instead of a specific company.

Peer Comparison

Generate a structured comparison of two or more companies across key dimensions in a single report.

Company News Monitoring

Fetch real-time, source-cited news articles for any company — synchronous, no polling required.

Supporting APIs

Company Search, File Upload, Report Status, and Download Report — all used alongside Company Research.