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 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.
| Workflow ID | Name | Type | Description |
|---|---|---|---|
customer_call_synthesis_462a7bb | Customer Call Synthesis | Company | Summarise customer feedback insights and key discussion points from call transcripts |
fact_sheet_v1_274e768 | Deal Factsheet | Company | Generate a concise deal snapshot for IC review — one-pager format |
expert_call_synthesis_f6a6a60 | Expert Call Synthesis | Company | Summarise key insights and takeaways from expert interviews |
ic_memo_(direct_investments)_02918b9 | IC Memo (Direct Investments) | Company | Create a full investment memo for evaluating direct investment opportunities |
ic_memo_(fund)_e41b13a | IC Memo (Fund) | Company | Structured due diligence memo on a target fund |
value_chain_v1_bac0ea9 | Value Chain Analysis | Company | Analyse activities across the value chain to identify value creation and efficiency opportunities |
week_0_cdd_fact_pack_c0fd566 | Week-0 CDD Factpack | Company | Build a factpack for preliminary commercial due diligence |
martec_cim_review_memo_71a4d4a | CIM Review | Company | Analyse a Confidential Information Memorandum for strategic deal insights |
value_creation_e469641 | M&A Opportunity Identification | Company | Identify potential acquisition themes for a company based on strategic desirability and feasibility |
industry_research___custom_a842447 | Industry Attractiveness | Industry | Assess industry attractiveness, market potential, and competitive dynamics |
industry_level_unit_economics_ac92754 | Industry Unit Economics (beta) | Industry | Analyse industry-level unit economics and margin structures |
new_market_sizing_work | Market Sizing (beta) | Industry | Estimate total addressable market opportunity for a defined space |
company_teaser_ad4f4ca | Company Teaser | Company | Generate a concise, deal-ready company teaser for deal marketing purposes |
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
Endpoint| Parameter | Type | Required | Description |
|---|---|---|---|
workflow | string | Required | The workflow ID for the template you want to run. Copy the ID exactly from the table in Section 1 (e.g. "value_creation_e469641"). Unlike the other Workflow APIs, this is not a fixed value — it selects which specialist template to execute. |
permalink | string | Required for company workflows* | Wokelo/Crunchbase permalink of the company (e.g. "air-canada", "salesforce"). Use the Company Search API to resolve a company name to its permalink. Required for all company-type workflows. |
website | string | Required for company workflows* | Full URL of the company’s website (e.g. "https://www.aircanada.com"). Accepted as an alternative to permalink when the permalink is unknown. |
industry_research_topic | string | Context-dependent | For company workflows: optional industry override — leave blank to use Wokelo’s auto-detected industry. For industry workflows: required — the industry, sector, or topic to analyse (e.g. "Electric vehicles", "B2B SaaS payments"). |
workbook_name | string | Optional | Label for the generated report workbook. Defaults to a generic name if omitted. Useful for identifying reports in subsequent status and download calls. |
custom_files | object[] | Optional | Array of file references to include in the report alongside Wokelo’s synthesis. Each object should use the fileName value returned by the File Upload API. Use this to incorporate CIMs, management presentations, expert call transcripts, or proprietary research. |
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.5. Response
Submission response
The initial POST returns immediately with a single field:| Field | Type | Description |
|---|---|---|
report_id | integer | Unique identifier for this report job. Store immediately — it is the only handle to your report and cannot be recovered if lost. |
Report status response
PollGET /api/assets/get_notebook_status/?report_id={report_id} until the status field is "Completed".
| Status value | Meaning |
|---|---|
"Pending" | Report is queued and waiting to start. |
"Processing" | Report generation is in progress. |
"Completed" | Report is ready to download. |
"Failed" | Report generation encountered an error. Retry the submission. |
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
| Field | Type | Present in | Description |
|---|---|---|---|
summary | string | Most sub-keys | Main narrative content for this step or section. Often markdown-formatted with bold text, tables, and source brackets [1-5]. |
source | object[] | Most sub-keys | Array of citation objects: {id, title, url, publisher, date}. |
quick_snapshot | object | Company snapshot steps | Firmographic card with company_firmographics and product_details objects (same schema as Company Research Quick Snapshot). |
value_creation_e469641) — example structure:
Download format options
file_type | Description |
|---|---|
"json" | Fully structured JSON — all sections, step sub-keys, summary content, and source citations. Best for programmatic processing, pipeline ingestion, or downstream analysis. |
"pdf" | Formatted PDF. Best for sharing with stakeholders as a finished deliverable. |
"docx" | Editable Word document. Best for teams that customise or annotate outputs before distribution. |
"ppt" | PowerPoint presentation. Best for IC presentations, LP updates, and deal memos. |
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.
| Status | Meaning | Cause & Resolution |
|---|---|---|
200 OK | Request accepted | report_id returned. Proceed to polling. |
400 Bad Request | Invalid parameters | Missing workflow, unrecognised workflow ID, missing company identifier for a company-type workflow, or missing industry_research_topic for an industry-type workflow. Check the detail field. |
401 Unauthorized | Auth failed | The Authorization header is missing or contains an invalid token. Verify your key in Settings → API Keys. |
403 Forbidden | Insufficient access | Your plan does not include access to this workflow template. Contact support@wokelo.ai. |
429 Too Many Requests | Rate limit exceeded | Implement exponential back-off on submission. The response includes a Retry-After header. |
500 Internal Server Error | Server error | Retry the submission after a brief delay. If the issue persists, contact support@wokelo.ai. |
"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.