Skip to main content

1. Overview

The Custom Workflow API gives you programmatic access to Wokelo’s full library of specialist research workflows — templates that go well beyond the standard Company Research, Industry Research, and Peer Comparison formats. Each workflow is purpose-built for a specific investment or diligence use case, producing a structured output tailored to that task rather than a generic company or sector brief. 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:
What makes Custom Workflow different from other Workflow APIs:
  • The workflow field is a variable workflow ID — not a fixed string like "company_primer" or "industry_primer". Each pre-built template has its own ID (e.g. "value_creation_e469641", "ic_memo_(direct_investments)_02918b9"). You select the template by passing its ID.
  • The required input fields depend on the workflow type: company-focused workflows require permalink or website; industry-focused workflows require industry_research_topic. Some workflows accept both.
  • The output structure varies by workflow — each template produces its own named sections and step structure, rather than a fixed schema.
  • The endpoint, auth mechanism, polling flow, and download mechanics are identical to all other Workflow APIs. Only the workflow ID and inputs change.
Available pre-built workflows:
This API uses the same endpoint, auth mechanism, polling flow, and download mechanics as Company Research, Industry Research, and Peer Comparison. The only differences are the workflow ID you pass and the input fields required by that workflow type.

2. Quick Start

Step 1 — Submit a company workflow request
Step 1 (alternative) — Submit an industry workflow 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.
For company-type workflows (all except industry_research___custom_a842447, industry_level_unit_economics_ac92754, and new_market_sizing_work), either permalink or website is required. For industry-type workflows, industry_research_topic is required and no company identifier is needed. The industry_research_topic field serves double duty — as an optional industry label in company workflows, and as the primary research topic in industry workflows.
Full request examples:

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

Unlike Company Research, Industry Research, and Peer Comparison — which have fixed, predictable section names — Custom Workflow output structures vary by workflow ID. Each template produces its own named top-level sections and nested sub-keys. General structural patterns:
  • Multi-step workflows (like M&A Opportunity Identification, IC Memos) produce step-keyed top-level sections, e.g. "Step 1: Company Information", "Step 2: Company Intent Identification", "Step 3: Opportunity Mapping", with a summary scorecard section (e.g. "Investment Prioritization Scorecard")
  • Single-output workflows (like Company Teaser, Deal Factsheet, CIM Review) produce a single section or a small number of named output blocks
  • Within each step, sub-keys use a UUID-suffixed naming convention (e.g. "CP - Quick snapshot_3b3f08c6-d285-4bb6-9b50-93c7e87cea9d") — meaning sub-key names are not deterministic and must be discovered by iterating the keys of each section
Recommended navigation pattern:
Common sub-key fields across workflow types: M&A Opportunity Identification (value_creation_e469641) — example structure:

Download format options


6. Examples

M&A Opportunity Identification for a company

Identify potential acquisition themes and opportunity scoring for a company.
Sample submission response:

Industry Attractiveness assessment

Run an industry-type workflow to assess attractiveness and potential for a sector.

CIM Review with an uploaded document

Upload a CIM file and run the CIM Review workflow to get AI-synthesised deal insights.
Because sub-keys within each section use UUID-suffixed names, navigate by iterating rather than hardcoding paths.

Batch custom workflows across a portfolio

Run M&A Opportunity Identification or IC Memo workflows across a set of companies concurrently.

Expert Call Synthesis with a transcript file

Upload a call transcript and run Expert Call Synthesis to extract structured takeaways.

7. Error Handling

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

8. Best Practices

Copy workflow IDs exactly — capitalisation, underscores, and alphanumeric suffixes all matter Each workflow ID is a unique string including a short hash suffix (e.g. "value_creation_e469641", "ic_memo_(direct_investments)_02918b9"). Unlike "company_primer" or "industry_primer" which are clean, memorable strings, custom workflow IDs are exact identifiers. A single character difference returns a 400 error. Copy from the table in Section 1 — never type from memory. Know whether your workflow is company-type or industry-type before submitting Company-type workflows (all templates except the three industry ones) require permalink or website. Industry-type workflows (industry_research___custom_a842447, industry_level_unit_economics_ac92754, new_market_sizing_work) require industry_research_topic. Sending a company identifier to an industry workflow, or an industry topic without a company identifier to a company workflow, will return a 400 or produce an empty/incorrect report:
Use custom_files to get full value from transcript-based workflows The Customer Call Synthesis and Expert Call Synthesis workflows produce their most useful output when you upload the actual transcript alongside the request. Without custom_files, these workflows will attempt to synthesise from publicly available sources, which produces generic output. Always upload the source document first:
Navigate output JSON by iterating keys — do not hardcode paths Unlike Company Research (which has predictable fixed section names) and Industry Research (which always produces the same five sections), Custom Workflow output structures are workflow-specific and include UUID-suffixed sub-keys. Always iterate rather than hardcoding:
Store report_id immediately and durably The submission response contains only report_id. There is no list-reports endpoint to recover lost IDs. Store it to a database or log immediately after receiving the response. Use 20-second polling intervals — complex multi-step workflows can take 5–10 minutes Workflows with multiple research steps (IC Memo, M&A Opportunity Identification, Value Chain Analysis) run several parallel research jobs and typically complete in 5–10 minutes. Poll every 20 seconds with a progressive back-off:
Check workflow availability with your plan before building automations Some workflow templates may be gated to specific plan tiers. A 403 Forbidden on submission (not on polling) indicates your plan does not include access to that template. Contact support@wokelo.ai to confirm which templates are included in your plan before building production automations around them.

Company Research

The standard async company deep-dive — same endpoint and polling flow, fixed "company_primer" workflow producing a consistent five-section report.

Industry Research

The standard async industry primer — same endpoint and polling flow, fixed "industry_primer" workflow.

Peer Comparison

Side-by-side benchmarking of 2–5 companies — same endpoint, fixed "player_comparison" workflow.

Company News Monitoring

Real-time news feed for any company — synchronous, no polling. Useful for keeping custom workflow outputs current with latest developments.

Supporting APIs

File Upload, Report Status, and Download Report — all required to run Custom Workflow end-to-end.

Company Search

Resolve a company name to its Wokelo permalink — needed before passing permalink to any company-type workflow.