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 areport_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
workflowfield 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
permalinkorwebsite; industry-focused workflows requireindustry_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.
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 request3. Authentication
All requests must include a Bearer token in theAuthorization HTTP header.
4. Request Reference
EndpointFor 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.5. Response
Submission response
The initial POST returns immediately with a single field:Report status response
PollGET /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
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.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.Navigating the output JSON
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:
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:
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:
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:
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.
9. Related APIs
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.