# AGENTS Source: https://docs.wokelo.ai/AGENTS > **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project. > For Mintlify product knowledge (components, configuration, writing standards), > install the Mintlify skill: `npx skills add https://mintlify.com/docs` # Documentation project instructions ## About this project * This is a documentation site built on [Mintlify](https://mintlify.com) * Pages are MDX files with YAML frontmatter * Configuration lives in `docs.json` * Run `mint dev` to preview locally * Run `mint broken-links` to check links ## Terminology ## Style preferences * Use active voice and second person ("you") * Keep sentences concise — one idea per sentence * Use sentence case for headings * Bold for UI elements: Click **Settings** * Code formatting for file names, commands, paths, and code references ## Content boundaries # M&A Activity Source: https://docs.wokelo.ai/acquisitions POST https://api.wokelo.ai/api/workflow_manager/start/ ## Overview The M\&A Activity API surfaces the M\&A transactions that have taken place in a given industry domain. You can refine the output by transaction date, transaction status, transaction amount, and by attributes of the target company such as company type, geography, founding year, employee count, funding amount, and funding stage. M\&A Activity runs as a workflow. Set `workflow` to `acquisition_workflow` in the request body to start one. The request returns a `report_id`, which you then use to track completion and export the results. ## Endpoint Details * Method: POST * Endpoint: `/api/workflow_manager/start/` ## Authentication Requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request ### Body Parameters **topic** `string` *required* Industry topic to surface M\&A transactions for (e.g. `"HVAC in US"`) **workflow** `string` *required* The workflow to run. Must be `"acquisition_workflow"` for M\&A Activity. **workbook\_name** `string` *required* Name of the workbook that will hold the generated report (e.g. `"HVAC in US"`) **advanced\_settings** `object` Filter parameters object. All filters live inside `advanced_settings`. Include the object in every request, and send empty values (`[]`) for any filter you do not want to apply. #### Deal filters **transaction\_date** `object` Filter by the date of the transaction. Dates use the `YYYY-MM-DD` format. **from** `string` Earliest transaction date (inclusive), e.g. `"2023-10-28"` **to** `string` Latest transaction date (inclusive), e.g. `"2026-10-29"` **transaction\_status** `string[]` Filter by the status of the transaction. Pass an empty array to include all statuses. Supported array values: `"completed"`, `"announced"` **transaction\_amount** `object` Filter by transaction amount (in million USD). **from** `number` Minimum transaction amount, e.g. `10` **to** `number` Maximum transaction amount, e.g. `500` **transaction\_amount\_include\_blanks** `boolean` When `true`, transactions with no disclosed amount are included in the results alongside transactions that match the `transaction_amount` range. #### Target company filters **company\_type** `string` Type of company to include. Accepted values: `"private"`, `"public"`, `"all"` **geography** `string[]` Geographic scope. Pass `["Worldwide"]` for no geographic restriction, or a list of ISO country codes (e.g. `["USA", "GBR"]`). **founded\_year** `object` Filter by company founding year. **from** `integer` Minimum founding year (inclusive), e.g. `2010` **to** `integer` Maximum founding year (inclusive), e.g. `2020` **employee\_count** `string[]` Filter by employee headcount range. Pass an empty array to include all headcounts. Supported array values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+` **total\_funding** `object` Filter by total funding amount raised (in million USD). **from** `number` Minimum total funding, e.g. `1` **to** `number` Maximum total funding, e.g. `50` **total\_funding\_include\_blanks** `boolean` When `true`, companies with no reported total funding are included in the results alongside companies that match the `total_funding` range. **funding\_stage** `string[]` Filter by funding stage (e.g. `"Series A"`, `"Series B"`). Pass an empty array to include all stages. Supported array values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A`, `Series B`, `Series C`, `Series D`, `Series E`, `Series F`, `Series G`, `Series H`, `Series I`, `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others` ```json Basic request theme={"system"} { "topic": "HVAC in US", "workflow": "acquisition_workflow", "workbook_name": "HVAC in US", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "funding_stage": [], "employee_count": [], "total_funding_include_blanks": true, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" }, "transaction_status": [], "transaction_amount_include_blanks": true } } ``` ```json Request with filters theme={"system"} { "topic": "HVAC in US", "workflow": "acquisition_workflow", "workbook_name": "HVAC in US", "advanced_settings": { "company_type": "private", "geography": ["USA"], "founded_year": { "from": 2000, "to": 2020 }, "funding_stage": ["Private equity round"], "employee_count": ["51-100", "101-250"], "total_funding": { "from": 1, "to": 50 }, "total_funding_include_blanks": false, "transaction_date": { "from": "2024-01-01", "to": "2026-10-29" }, "transaction_status": ["completed"], "transaction_amount": { "from": 10, "to": 500 }, "transaction_amount_include_blanks": false } } ``` ### Response A successful response returns a `report_id` that identifies the M\&A Activity report. #### Successful Response Fields **report\_id** `integer` Unique identifier for the report created by this request. Use it to track completion and to download the results (see below). ```json 200 theme={"system"} { "report_id": 123345 } ``` ## Tracking Completion and Exporting Results M\&A Activity generation is asynchronous. After you receive a `report_id`: 1. Use `/api/assets/get_notebook_status/` to track completion of the report. 2. Once the report is complete, use `/api/assets/download_report/` to export the results. # M&A Activity Source: https://docs.wokelo.ai/acquisitions-doc Surface M&A transactions in a given industry domain with deal amounts, acquirer and target profiles, and news context. ## 1. Overview The M\&A Activity API surfaces the M\&A transactions that have taken place in a given industry domain. Each record shows who acquired whom, at what price, on what date, what the target does, and relevant news coverage. This is an **asynchronous API**. Starting the workflow returns a `report_id`, which you use to track completion and export the results. See [How Async APIs work](/how-async-apis-work). Each transaction includes deal metadata (dates, status, amount), the acquirer profile, target firmographics and business profile, and curated news with source URLs. **Common use cases:** * **Competitive intelligence**: track which acquirers are most active in a sector * **Due diligence**: assemble precedent transactions for a category or acquirer * **Portfolio monitoring**: catch new deals in categories you track *** ## 2. Quick Start **Step 1: Start the workflow** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "topic": "HVAC in US", "workflow": "acquisition_workflow", "workbook_name": "HVAC in US", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "funding_stage": [], "employee_count": [], "total_funding_include_blanks": true, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" }, "transaction_status": [], "transaction_amount_include_blanks": true } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "topic": "HVAC in US", "workflow": "acquisition_workflow", "workbook_name": "HVAC in US", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "funding_stage": [], "employee_count": [], "total_funding_include_blanks": True, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" }, "transaction_status": [], "transaction_amount_include_blanks": True } } ) print(response.json()["report_id"]) ``` The response contains a `report_id`. **Step 2: Track completion** Use `/api/assets/get_notebook_status/` with the `report_id` to check whether the report has completed. **Step 3: Export results** Once the report is complete, use `/api/assets/download_report/` with the `report_id` to export the results. *** ## 3. Authentication Include a Bearer token in the `Authorization` header of every request. ```text theme={"system"} Authorization: Bearer ``` Obtain a token from the `/auth/token/` endpoint using the client id and client secret under **Account Details → API Credentials** in the Wokelo dashboard. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access. > [!WARNING] > > Never expose your token in client-side code or public repositories. *** ## 4. Request Reference **Endpoint** ```text theme={"system"} POST https://api.wokelo.ai/api/workflow_manager/start/ ``` The request body is JSON. Include `advanced_settings` in every request and send empty values (`[]`) for filters you do not want to apply. Dates use the `YYYY-MM-DD` format. | Parameter | Type | Required | Description | | - | - | - | - | | `topic` | string | **Required** | Industry topic to surface M\&A transactions for (e.g. `"HVAC in US"`). | | `workflow` | string | **Required** | Must be `"acquisition_workflow"`. | | `workbook_name` | string | **Required** | Name of the workbook that holds the generated report. | | `advanced_settings` | object | Optional | Filter parameters. All filters below live inside this object. | | `advanced_settings.transaction_date` | object | Optional | Object with `from` and/or `to` (`YYYY-MM-DD`, inclusive). | | `advanced_settings.transaction_status` | string\[] | Optional | `"completed"`, `"announced"`. Empty array includes all statuses. | | `advanced_settings.transaction_amount` | object | Optional | Object with `from` and/or `to`, in million USD. | | `advanced_settings.transaction_amount_include_blanks` | boolean | Optional | When `true`, transactions with no disclosed amount are included. | | `advanced_settings.company_type` | string | Optional | `"private"`, `"public"` or `"all"`. | | `advanced_settings.geography` | string\[] | Optional | `["Worldwide"]` for no restriction, or ISO country codes (e.g. `["USA", "GBR"]`). | | `advanced_settings.founded_year` | object | Optional | Object with `from` and/or `to` (integer years, inclusive). | | `advanced_settings.employee_count` | string\[] | Optional | Headcount bands. Empty array includes all. Values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+`. | | `advanced_settings.total_funding` | object | Optional | Target total funding. Object with `from` and/or `to`, in million USD. | | `advanced_settings.total_funding_include_blanks` | boolean | Optional | When `true`, companies with no reported total funding are included. | | `advanced_settings.funding_stage` | string\[] | Optional | Empty array includes all. Values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A` to `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others`. | *** ## 5. Response ### Workflow start response ```json theme={"system"} { "report_id": 117253 } ``` | Field | Type | Description | | - | - | - | | `report_id` | integer | Unique identifier of the report. Use it to track completion and export results. | ### Report output fields | Field | Description | | - | - | | `Permalink` | Stable unique identifier for the transaction. Use it as a primary key. | | `Deal Date (Announced)`, `Deal Completion Date` | `YYYY-MM-DD`. Completion date is null for pending deals. | | `Deal Status` | `Complete` or `Pending`. | | `Deal Amount ($M)` | Transaction value. Null when undisclosed. | | `Acquirer Name`, `Acquirer Website`, `Acquirer Type` | Acquirer details. Type is `Strategic` or `Institutional`. | | `Target Name`, `Target Website` | Acquired company and its primary domain. | | `Target HQ City`, `Target HQ Country`, `Target HQ Continent`, `Target Founded` | Target headquarters and founding year. | | `Target Employees (Crunchbase)`, `Target Employees (LinkedIn)` | Headcount band and numeric headcount. | | `Target Product Category`, `Target Core Offering`, `Target Product Catalog` | Target product category, AI-generated description and key products. | | `News` | Unstructured text of news summaries, each followed by a source URL. Null when no coverage was indexed. | *** ## 6. Examples ### Filtered M\&A transactions Completed deals for private HVAC targets in the USA between 2024 and 2026, valued at \$10M to \$500M. ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "topic": "HVAC in US", "workflow": "acquisition_workflow", "workbook_name": "HVAC in US", "advanced_settings": { "company_type": "private", "geography": ["USA"], "founded_year": { "from": 2000, "to": 2020 }, "funding_stage": ["Private equity round"], "employee_count": ["51-100", "101-250"], "total_funding": { "from": 1, "to": 50 }, "total_funding_include_blanks": false, "transaction_date": { "from": "2024-01-01", "to": "2026-10-29" }, "transaction_status": ["completed"], "transaction_amount": { "from": 10, "to": 500 }, "transaction_amount_include_blanks": false } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "topic": "HVAC in US", "workflow": "acquisition_workflow", "workbook_name": "HVAC in US", "advanced_settings": { "company_type": "private", "geography": ["USA"], "founded_year": { "from": 2000, "to": 2020 }, "funding_stage": ["Private equity round"], "employee_count": ["51-100", "101-250"], "total_funding": { "from": 1, "to": 50 }, "total_funding_include_blanks": False, "transaction_date": { "from": "2024-01-01", "to": "2026-10-29" }, "transaction_status": ["completed"], "transaction_amount": { "from": 10, "to": 500 }, "transaction_amount_include_blanks": False } } ) print(response.json()["report_id"]) ``` *** # Add Company Source: https://docs.wokelo.ai/add-company POST /api/enterprise/company/add/ ## Overview Add a company to the Wokelo database when it cannot be found using the Company Search API. This is an asynchronous request that returns a `request_id`. Once the request is completed, the result contains the `permalink` of the newly added company, which can then be used across other Wokelo APIs. ## Endpoint Details * **Method:** POST * **Endpoint:** `/api/enterprise/company/add/` NOTE: This is an asynchronous API. After submitting a request, poll the request status endpoint and retrieve the output using the request result endpoint. Learn more in [How Async APIs work](https://docs.wokelo.ai/how-async-apis-work). ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request **Content-Type** `string` *required* Must be set to `application/json` #### Body Parameters **company\_name** `string` *required* Name of the company to add. Example: `Aditi Solar` **website** `string` *required* Full URL of the company's website. Example: `https://aditisolar.in/` **product\_category** `string` Product or industry category of the company. **company\_type** `string` Type of the company. Supported values: `Public`, `Private` **Sample Request Body** ```json theme={"system"} { "company_name": "Aditi Solar", "website": "https://aditisolar.in/" } ``` ## Response **Successful Response Fields** Returns a JSON object with the following structure: **request\_id** `string` Unique identifier for the request. Use this to check status and retrieve the result. **status** `string` Current status of the request (e.g., `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`). **Sample Response** ```json theme={"system"} { "request_id": "89daf26a-ee17-4915-96da-19b52067068a", "status": "PENDING" } ``` ## Retrieving the Result Once the request status is `COMPLETED`, use the request result endpoint to fetch the output. ```bash theme={"system"} curl --location 'https://api.wokelo.ai/api/enterprise/request/result/?request_id=89daf26a-ee17-4915-96da-19b52067068a' \ --header 'Authorization: Bearer {YOUR TOKEN}' \ --header 'Content-Type: application/json' ``` **Completed Result Fields** **request\_id** `string` Unique identifier for the request. **status** `string` Status of the request — `COMPLETED` when the company has been added. **result** `object` Result object containing the outcome of the add operation. * `status` — `"success"` if the company was added successfully. * `permalink` — Unique identifier/slug for the newly added company. **credits\_consumed** `number` Number of credits consumed by the request. **Sample Completed Result** ```json theme={"system"} { "request_id": "89daf26a-ee17-4915-96da-19b52067068a", "status": "COMPLETED", "result": { "status": "success", "permalink": "wokelo-aditisolar-in" }, "credits_consumed": 0.0 } ``` ```json 200 theme={"system"} { "request_id": "89daf26a-ee17-4915-96da-19b52067068a", "status": "PENDING" } ``` ## OpenAPI ```yaml POST /api/enterprise/company/add/ theme={"system"} openapi: 3.0.3 info: title: Wokelo API description: > Wokelo provides four categories of APIs for company and market intelligence: 1. **Enrichment** – Company and Industry data using Wokelo database and alternative data. Supports multi-company requests. 2. **Discovery** – Workflows for specific use-cases such as market map, target screening, and buyer screening. 3. **Monitoring** – Real-time news monitoring for companies. 4. **Workflow Automation** – Wokelo and custom research workflows executed within notebooks. Enrichment and Discovery APIs are managed through async requests; use the Supporting APIs to track status and export results in JSON. Workflow APIs are executed within notebooks and support export to PDF, PPT, DOC, or JSON. **Authentication:** All endpoints (except `/auth/token/`) require a Bearer JWT token in the `Authorization` header. version: 1.0.0 contact: url: https://docs.wokelo.ai/contact servers: - url: https://api.wokelo.ai description: Production server security: [] tags: - name: Supporting APIs description: >- Utility endpoints for search, file upload, request management, and report retrieval externalDocs: description: Official Wokelo API Documentation url: https://docs.wokelo.ai/overview paths: /api/enterprise/company/add/: post: tags: - Supporting APIs summary: Add Company description: >- Add a company to the Wokelo database when it cannot be found via Company Search. This is an asynchronous request that returns a request_id; poll the request status endpoint and retrieve the resulting permalink via the request result endpoint. operationId: addCompany requestBody: required: true content: application/json: schema: type: object required: - company_name - website properties: company_name: type: string description: Name of the company to add. example: Aditi Solar website: type: string format: uri description: Full URL of the company's website. example: https://aditisolar.in/ product_category: type: string description: Product or industry category of the company. company_type: type: string enum: - Public - Private description: Type of the company. example: company_name: Aditi Solar website: https://aditisolar.in/ responses: '200': description: Request accepted and queued for processing content: application/json: schema: type: object properties: request_id: type: string description: >- Unique identifier for the request. Use this to check status and retrieve the result. example: 89daf26a-ee17-4915-96da-19b52067068a status: type: string description: Current status of the request. enum: - PENDING - PROCESSING - COMPLETED - FAILED - CANCELLED example: PENDING example: request_id: 89daf26a-ee17-4915-96da-19b52067068a status: PENDING '401': description: Unauthorized – invalid or missing JWT token security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token obtained from the `/auth/token/` endpoint. ``` # Additional resources Source: https://docs.wokelo.ai/additional-resources ## Polling strategy All async APIs require polling. Poll the status endpoint **once per minute** for up to **90 minutes**. If your request has not completed within 90 minutes, treat it as timed out — our team is automatically notified and will investigate promptly. ```json JavaScript expandable wrap theme={"system"} async function pollRequest(requestId, token, opts = {}) { const { maxAttempts = 90, interval = 60000, // 1 minute between each poll } = opts; for (let i = 0; i < maxAttempts; i++) { const res = await fetch( `https://api.wokelo.ai/api/enterprise/request/status/?request_id=${requestId}`, { headers: { Authorization: `Bearer ${token}` } } ); const { status } = await res.json(); if (status === "COMPLETED") return fetchResult(requestId); if (status === "FAILED") throw new Error("Request failed"); await new Promise(r => setTimeout(r, interval)); } // Timed out after 90 minutes — our team will be notified and look into it. throw new Error( "Polling timed out after 90 minutes. Our team has been notified and will investigate." ); } ``` ```json Python expandable wrap theme={"system"} import time import requests def poll_request(request_id: str, token: str, max_attempts: int = 90, interval: int = 60): """ Polls the status endpoint once per minute for up to 90 minutes. Raises an exception if the request does not complete within 90 minutes. """ headers = {"Authorization": f"Bearer {token}"} for attempt in range(max_attempts): response = requests.get( f"https://api.wokelo.ai/api/enterprise/request/status/", params={"request_id": request_id}, headers=headers ) response.raise_for_status() status = response.json().get("status") if status == "COMPLETED": return fetch_result(request_id) if status == "FAILED": raise Exception("Request failed.") time.sleep(interval) # Timed out after 90 minutes — our team will be notified and look into it. raise TimeoutError( "Polling timed out after 90 minutes. Our team has been notified and will investigate." ) ``` ## Error guides | **HTTP Code** | **Meaning** | **Retry?** | **Action** | | :- | :- | :- | :- | | `200` | Success (sync) | No | Parse response | | `202` | Accepted (async) | No | Poll with request\_id | | `400` | Bad Request | No | Fix request parameters | | `401` | Unauthorized | Once | Re-authenticate, then retry | | `403` | Forbidden | No | Check API access level | | `404` | Not Found | No | Verify endpoint URL and resource ID | | `429` | Rate Limited | Yes | Exponential backoff (start 1s, max 60s) | | `500` | Server Error | Yes | Retry with backoff (max 3 retries) | | `502/503` | Service Unavailable | Yes | Retry with backoff (max 5 retries) | ## Webhooks Instead of polling for results after submitting a request, you can use **webhooks** to receive the data automatically once processing is complete. When a request finishes, we'll send the payload directly to your configured endpoint — no repeated status checks required. Webhook configuration is handled by our customer success team. Please reach out to our Customer Success team to get webhook endpoint registered and activated. #### How It Works 1. Submit an enrichment request via any of the supported endpoints (e.g. `POST /api/enterprise/company/enrich/`). You'll receive a `request_id` with a `PENDING` status as usual. 2. Once processing is complete, we'll send an HTTP `POST` request to your registered webhook URL. 3. Your server should respond with a `200 OK` to acknowledge receipt. Here is sample payload. ```json wrap theme={"system"} { "request_id": "5b5c8248-50e3-4e5d-b91e-5c75378971dd", "status": "COMPLETED" } ``` # Affinity Source: https://docs.wokelo.ai/affinity ## Overview Wokelo seamlessly integrates with Affinity CRM to auto-generate research and enrich your pipeline in a secure, compliant way. By bridging due diligence with relationship management, we eliminate manual data entry and embed updated, context-aware insights directly into your workflow—empowering your team to evaluate opportunities faster than before. ## Key Capabilities & Workflows ### Enterprise-Grade Security We operate on a restricted user model, accessing only the specific lists you explicitly authorize. Your sensitive pipelines, private notes, and contact data remain completely isolated from the integration. ### Automated Research Triggers Instantly launch analysis based on deal activity. Adding a company to a list or updating a status field triggers Wokelo to generate the appropriate output—from preliminary screening recommendations to deep-dive investment memos. * **Company stage change:** Updating an organization's deal stage triggers a company research workflow. * **New company added:** Adding a new organization initiates a new company research flow automatically. ### Bespoke Workflow Execution We execute your custom workflows and write structured outputs back into Affinity. ### Seamless Company Enrichment Wokelo writes insights directly back into your workflow. We can push sections from your custom workflows to the companies' notes, ensuring data is always decision-ready. ![Image](https://mintcdn.com/wokeloai-7cd44985/dKe20VPK_eRnD3BP/images/image-24.png?fit=max\&auto=format\&n=dKe20VPK_eRnD3BP\&q=85\&s=8127d8805170d5a89ff22bc711e05c98) ![Image](https://mintcdn.com/wokeloai-7cd44985/dKe20VPK_eRnD3BP/images/image-25.png?fit=max\&auto=format\&n=dKe20VPK_eRnD3BP\&q=85\&s=65de74e8c3f17c8bc3209973002c16fd) ![Image](https://mintcdn.com/wokeloai-7cd44985/dKe20VPK_eRnD3BP/images/image-26.png?fit=max\&auto=format\&n=dKe20VPK_eRnD3BP\&q=85\&s=2a0328248f700f2cbce866e9fc8e0edc) ![Image](https://mintcdn.com/wokeloai-7cd44985/dKe20VPK_eRnD3BP/images/image-27.png?fit=max\&auto=format\&n=dKe20VPK_eRnD3BP\&q=85\&s=377642d3befcfac6117a0335fa5dfaff) ## Use Cases * **New organization added:** When a new company is added to your Affinity CRM, Wokelo automatically kicks off the right research workflow for that company. There's no need for your team to manually request, track, or manage research reports—everything starts running in the background as soon as the company appears. * **Stage change:** When a company moves from one stage to another (for example, from Screening to Under Diligence), Wokelo detects the change and automatically runs the relevant research for that stage. This ensures your team always has the right level of insight at the right point in the deal cycle. * **Insights enrichment:** Wokelo can also push key insights from its reports directly back into Affinity. These insights can be written into company notes or any custom field you choose, so your CRM stays continuously enriched with up-to-date, decision-ready intelligence. ## Get Started Ready to automate your research and enrich Affinity with decision-ready insights? Click below and our team will reach out to help set up your integration. [Integrate Affinity →](/contact) # Airtable Source: https://docs.wokelo.ai/airtable ## Overview Connect your Airtable instance with Wokelo to trigger AI-powered research directly from your base. Automatically generate company and industry research reports based on custom conditions, and receive real-time status updates and report URLs back into Airtable via webhooks. **Prerequisites:** Wokelo API access and an Airtable Team or Enterprise plan (required for custom scripting). ## Key Features * Trigger company and industry research based on custom conditions (e.g., when a deal stage changes to "In Progress") * Auto-update report status in your base as reports are generated * Populate report URLs directly into Airtable without leaving the page ## Set Up Your Airtable Base Create a new Workspace and Base in Airtable. We recommend including the following columns in your table: | Column | Type | Notes | | :- | :- | :- | | Website | URL | Company's website | | Product Category | Single select | e.g., "Electric Cars" — used to define industry for research | | Company Research Status | Single select | Values: Initiated, Completed | | Company Research Report ID | Number | | | Company Research URL | URL | | | Industry Research Status | Single select | Values: Initiated, Completed | | Industry Research Report ID | Number | | | Industry Research URL | URL | | ## Configure Automation Triggers Both Company Research and Industry Research follow the same automation pattern. **2a. Create the trigger** Go to the **Automations** tab, click **Add Trigger**, and select **When Record Updated**. Choose the relevant Table, View, and field to track (e.g., Deal Status). **2b. Add conditional logic** Click **Add Advanced Logic or Action** and select **Conditional Logic**. Example condition: trigger when Deal Status changes to "New" and the Report ID field is empty (to prevent duplicate reports). **2c. Set status to "Initiated"** Add an **Update Record** action and set the relevant Research Status field to "Initiated". **2d. Run the script** Add a **Run a Script** action. In the script window, add the following input variables: * For **Company Research**: `industry` (mapped to the Product Category column) and `website` (mapped to the Website column) * For **Industry Research**: `industry` (mapped to the Product Category column) Then paste the relevant script below, replacing the placeholder credentials with your actuals from the [credentials management page](https://app.wokelo.ai/). **Company Research Script** ```javascript expandable wrap theme={"system"} const formdata = JSON.stringify({ "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD", "grant_type": "password", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET" }); const myHeaders1 = new Headers(); myHeaders1.append("Content-Type", "application/json"); let auth_result = await fetch("", { method: "POST", body: formdata, headers: myHeaders1 }); auth_result = await auth_result.json(); const myHeaders = new Headers(); myHeaders.append("Content-Type", "application/json"); myHeaders.append("Authorization", `Bearer ${auth_result.access_token}`); let inputConfig = input.config(); const raw = JSON.stringify({ "industry": inputConfig.industry, "website": inputConfig.website }); const report_id = await fetch("", { method: "POST", headers: myHeaders, body: raw }).then(r => r.json()).catch(console.error); output.set('wkl_report_id', report_id.report_id); ``` **Industry Research Script** — same as above but use this endpoint and only the `industry` input: ```javascript theme={"system"} ``` **2e. Save the Report ID** Add an **Update Record** action after the script. Map the Report ID field (e.g., "Report ID Company Research") dynamically to the `wkl_report_id` output from the script step. ## Configure Webhooks (for Status and URL Updates) Webhooks allow Wokelo to push report completion updates back into Airtable automatically. **3a. Create a new automation** Click **Create Automation** and name it (e.g., "Update URL and Status"). Add a trigger and select **When a webhook is received**. Copy the webhook URL from the right panel and share it with your Wokelo account manager — they will configure it within 24 business hours. You can continue setup in the meantime. **3b. Filter by report type** Add a **Conditional Logic** block. Set the condition: `body > report_type` contains "Company" or "Industry" (one condition per automation, depending on which report type you're handling). **3c. Find the matching record** Add a **Find Records** action. Set the condition to match the relevant Report ID column (e.g., "Report ID Company Research") against `body > report_id` from the webhook payload (set to Dynamic via the gear icon). **3d. Update status and URL** Add an **Update Record** action. Map the Record ID from the Find Records step, then: * Set the Research Status field to "Completed" * Set the Report URL field to `https://app.wokelo.ai/notebook/` followed by `body > report_id` (dynamic) **Enable both automations** to ensure the full workflow runs end to end. ## Best Practices * Set the Product Category / Industry field as **Single Select** type — required for research to function correctly. If left blank, Wokelo will auto-assign an industry. * Always add an **empty Report ID condition** to prevent duplicate reports from being triggered. * Share your webhook URL with your Wokelo account manager as early as possible to avoid delays. # Login Source: https://docs.wokelo.ai/authentication POST /auth/token/ Obtain a JSON Web Token (JWT) for subsequent API authentication All API requests must be authenticated using a JWT token. Follow the steps below to generate your token: ## Overview Obtain a JSON Web Token (JWT) ffor subsequent API authentication ## Endpoint Details * **Method:** POST * **Endpoint:** `/auth/token/` ## Request ### Request Parameters Submit the following parameters as form-data in the request body: **client\_id** `string` *required* Unique identifier for your organization, obtained from the [API Credentials page](https://app.wokelo.ai/dashboard/profile/api-credentials) **client\_secret** `string` *required* Secret key for your organization, obtained from the [API Credentials page](https://app.wokelo.ai/dashboard/profile/api-credentials) **username** `string` *required* Your email address used for Wokelo login **password** `string` *required* Your account password used for Wokelo login **grant\_type** `string` *required* Type of grant being requested (use `"password"` for credential-based authentication) ## Response ### Response Fields On successful authentication (HTTP 200), the response will contain: **access\_token** `string` JWT for authenticated API access **expires\_in** `integer` Token validity duration in seconds **token\_type** `string` Type of authentication token **scope** `string` Authorization scope of the token **refresh\_token** `string` Token used to obtain a new access token * Ensure the `client_id` and `client_secret` are kept confidential * Any token returned by the API is sensitive and should be stored securely. Wokelo tokens are long-lasting and should never be exposed on the client side. * The access token is time-limited; use the refresh token to obtain a new access token when it expires * Use HTTPS for all authentication requests ```json 200 theme={"system"} { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 2628288, "token_type": "Bearer", "scope": "read write", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` # Box Source: https://docs.wokelo.ai/box ## Overview Connect your Box account to Wokelo and seamlessly convert your existing documents into AI-powered research insights. Through a secure OAuth connection, select files directly from Box and feed them into our research agents to generate actionable analysis—no data migration required. ## Integration Capabilities * **Comprehensive file support** — Word, PowerPoint, Excel, PDF, text, CSV. * **Preserves your workflow** — Works with existing folder structures without reorganization * **Enterprise security** — Fully encrypted and SOC 2 Type II compliant ## Use-cases * **Due diligence research** — Analyze CIMs, board decks, and KPI files for comprehensive company assessments * **Custom workflow integration** — Incorporate Box documents into tailored research processes * **Intelligent document querying** — Ask natural language questions like "What is the latest ARR by region?" across your file library * **Report generation** — Create investor briefs, DDQs, and presentation decks directly from selected Box content ## How it works Selecting files from Box is a seamless step while running your workflows on Wokelo * On the file upload step, click on ‘Box’ ![Image](https://mintcdn.com/wokeloai-7cd44985/0I6NdL_2xlDv-r30/images/image-52.png?fit=max\&auto=format\&n=0I6NdL_2xlDv-r30\&q=85\&s=97d35cccc732734d74b0d3860f6c13cf) * If you’re uploading files for the first time, you might be redirected to a login screen to authenticate your account. ![Image](https://mintcdn.com/wokeloai-7cd44985/0I6NdL_2xlDv-r30/images/image-53.png?fit=max\&auto=format\&n=0I6NdL_2xlDv-r30\&q=85\&s=c6ea7108748fd41e8f8044ec6e0b906e) * This brings up the files you have available in Box. Select the relevant files you want to be included in your research and click on the Checkbox in the bottom right corner to upload the selected files. ![Image](https://mintcdn.com/wokeloai-7cd44985/0I6NdL_2xlDv-r30/images/image-54.png?fit=max\&auto=format\&n=0I6NdL_2xlDv-r30\&q=85\&s=9168ab32518edc40ba17a269928c6ac2) > [!NOTE] > > In a folder, you also have an option to select all files (upto a maximum of 1000). This enables you to upload all the files relevant for a research without selecting them individually. * Once uploaded, you would see a list of files that will be used in the workflow. Click Next to trigger the report with the relevant files ![Image](https://mintcdn.com/wokeloai-7cd44985/0I6NdL_2xlDv-r30/images/image-55.png?fit=max\&auto=format\&n=0I6NdL_2xlDv-r30\&q=85\&s=5f5093652fd69676455525c74f8c4ec7) [Integrate Box →](/contact) # Buyer Screening Source: https://docs.wokelo.ai/buyer-screening POST https://api.wokelo.ai/api/workflow_manager/start/ ## Overview The Buyer Screening API generates a long list of potential buyers for a given target company, enriched with structured data. You can refine the output with a detailed query, sample companies, buyer type, company type, and geography to narrow the strategic criteria. Buyer Screening runs as a workflow. Set `workflow` to `buyer_analysis` in the request body to start one. The request returns a `report_id`, which you then use to track completion and export the results. ## Endpoint Details * Method: POST * Endpoint: `/api/workflow_manager/start/` ## Authentication Requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request ### Body Parameters **topic** `string` *required* The sector or theme describing the target's business (e.g. `"Civil Engineering Infrastructure Services"`) **workflow** `string` *required* The workflow to run. Must be `"buyer_analysis"` for Buyer Screening. **workbook\_name** `string` *required* Name of the workbook that will hold the generated buyer list (e.g. `"Ulteig Buyers"`) **advanced\_settings** `object` *required* Target and filter parameters object. Include the object in every request, and send empty values (`""`, `[]`) for any filter you do not want to apply. **target** `string` *required* Permalink of the target company or its complete URL (e.g. `"ulteig"` OR `"https://www.ulteig.com/"`) **detailed\_query** `string` A descriptive query to refine the buyer search scope and strategic criteria. **companies** `string[]` Permalinks of representative companies or their complete URLs to anchor the buyer search. **buyer\_type** `string[]` Type of buyer to target. Pass an empty array to include all buyer types. Accepted values: `"strategic"`, `"financial"` **company\_type** `string` Type of company to include. Accepted values: `"private"`, `"public"`, `"all"` **geography** `string[]` Geographic scope. Pass `["Worldwide"]` for no geographic restriction, or a list of ISO country codes (e.g. `["USA", "GBR"]`). ```json Basic request theme={"system"} { "topic": "Civil Engineering Infrastructure Services", "workflow": "buyer_analysis", "workbook_name": "Ulteig Buyers", "advanced_settings": { "target": "ulteig", "detailed_query": "Civil Engineering Infrastructure Services", "companies": [], "buyer_type": [], "company_type": "all", "geography": ["Worldwide"] } } ``` ```json Request with filters theme={"system"} { "topic": "Civil Engineering Infrastructure Services", "workflow": "buyer_analysis", "workbook_name": "Ulteig Buyers", "advanced_settings": { "target": "ulteig", "detailed_query": "Engineering and consulting firms seeking to expand infrastructure services", "companies": [], "buyer_type": ["strategic"], "company_type": "public", "geography": ["USA", "CAN"] } } ``` ### Response A successful response returns a `report_id` that identifies the buyer screening report. #### Successful Response Fields **report\_id** `integer` Unique identifier for the report created by this request. Use it to track completion and to download the results (see below). ```json 200 theme={"system"} { "report_id": 117253 } ``` ## Tracking Completion and Exporting Results Buyer Screening generation is asynchronous. After you receive a `report_id`: 1. Use `/api/assets/get_notebook_status/` to track completion of the report. 2. Once the report is complete, use `/api/assets/download_report/` to export the results. # Buyer Screening Source: https://docs.wokelo.ai/buyer-screening-doc Identify and score potential acquirers for a target company. ## 1. Overview The Buyer Screening API identifies and scores potential acquirers for a defined target company. Given a target and strategic criteria, the AI pipeline evaluates each candidate buyer and returns a ranked list with deal scores, synergy commentary and financial profiles. This is an **asynchronous API**. Starting the workflow returns a `report_id`, which you use to track completion and export the results. See [How Async APIs work](/how-async-apis-work). Each buyer receives an `Overall Score` (1 to 10) and four sub-scores: `Deal Feasibility Score`, `Product Synergy Score`, `Deal Precedent Score` and `Synergy Potential Score`, each with a written rationale, plus a `Commentary` summarising the deal thesis. **Common use cases:** * **Sell-side advisory**: generate a scored buyer universe for a sale process * **Private equity exits**: screen strategic and financial buyers for portfolio companies * **Corporate development**: identify acquirers for subsidiaries or divestitures *** ## 2. Quick Start **Step 1: Start the workflow** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "topic": "Civil Engineering Infrastructure Services", "workflow": "buyer_analysis", "workbook_name": "Ulteig Buyers", "advanced_settings": { "target": "ulteig", "detailed_query": "Civil Engineering Infrastructure Services", "companies": [], "buyer_type": [], "company_type": "all", "geography": ["Worldwide"] } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "topic": "Civil Engineering Infrastructure Services", "workflow": "buyer_analysis", "workbook_name": "Ulteig Buyers", "advanced_settings": { "target": "ulteig", "detailed_query": "Civil Engineering Infrastructure Services", "companies": [], "buyer_type": [], "company_type": "all", "geography": ["Worldwide"] } } ) print(response.json()["report_id"]) ``` The response contains a `report_id`. **Step 2: Track completion** Use `/api/assets/get_notebook_status/` with the `report_id` to check whether the report has completed. **Step 3: Export results** Once the report is complete, use `/api/assets/download_report/` with the `report_id` to export the results. *** ## 3. Authentication Include a Bearer token in the `Authorization` header of every request. ```text theme={"system"} Authorization: Bearer ``` Obtain a token from the `/auth/token/` endpoint using the client id and client secret under **Account Details → API Credentials** in the Wokelo dashboard. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access. > [!WARNING] > > Never expose your token in client-side code or public repositories. *** ## 4. Request Reference **Endpoint** ```text theme={"system"} POST https://api.wokelo.ai/api/workflow_manager/start/ ``` The request body is JSON. Include `advanced_settings` in every request and send empty values (`""`, `[]`) for filters you do not want to apply. | Parameter | Type | Required | Description | | - | - | - | - | | `topic` | string | **Required** | The sector or theme describing the target's business (e.g. `"Civil Engineering Infrastructure Services"`). | | `workflow` | string | **Required** | Must be `"buyer_analysis"`. | | `workbook_name` | string | **Required** | Name of the workbook that holds the generated report. | | `advanced_settings` | object | **Required** | Target and filter parameters. All fields below live inside this object. | | `advanced_settings.target` | string | **Required** | Permalink or full URL of the target company being sold (e.g. `"ulteig"`). | | `advanced_settings.detailed_query` | string | Optional | A descriptive query that refines the buyer search scope and strategic criteria. | | `advanced_settings.companies` | string\[] | Optional | Permalinks or full URLs of representative companies to anchor the buyer search. | | `advanced_settings.buyer_type` | string\[] | Optional | `"strategic"`, `"financial"`. Empty array includes all buyer types. | | `advanced_settings.company_type` | string | Optional | `"private"`, `"public"` or `"all"`. | | `advanced_settings.geography` | string\[] | Optional | `["Worldwide"]` for no restriction, or ISO country codes (e.g. `["USA", "GBR"]`). | *** ## 5. Response ### Workflow start response ```json theme={"system"} { "report_id": 117253 } ``` | Field | Type | Description | | - | - | - | | `report_id` | integer | Unique identifier of the report. Use it to track completion and export results. | ### Report output fields | Field | Description | | - | - | | `Permalink`, `Name`, `Website` | Wokelo company identifier, display name and primary domain. | | `HQ City`, `HQ Country`, `HQ Continent`, `Founded` | Headquarters location and founding year. | | `Type`, `Operating Status` | Ownership type (`Public` or `Private`) and status (e.g. `Operating`, `Acquired`, `IPO`). | | `Product Category`, `Core Offering`, `Product Catalog` | Primary product category, AI-generated description of the core business, and key products. | | `Employees (Crunchbase)`, `Employees (LinkedIn)` | Headcount band and numeric headcount. | | `Funding Stage`, `Total Funding`, `Last Funding Date`, `Key Investors` | Funding profile. Total funding is in USD. Typically empty for public companies. | | `Revenue`, `EBITDA`, `Net Income`, `Market Cap`, `Enterprise Value`, `Ticker`, margins and multiples | Financial data in USD, primarily populated for public companies. | | `Acquisitions`, `Investments` | Past acquisitions (with year) and notable investments. May be empty. | | `Buyer Type` | `Strategic`, `Financial` or `Institutional`. | | `Overall Score`, `Overall Score Rationale` | Composite strategic fit (1 to 10) and a one-sentence rationale. | | `Deal Feasibility Score` | Whether the buyer can financially execute the deal. | | `Product Synergy Score` | Product and capability overlap with the target. | | `Deal Precedent Score` | Alignment with the buyer's historical M\&A pattern and deal size. | | `Synergy Potential Score` | Revenue and cost synergy opportunity. | | `Commentary` | AI-written deal thesis covering rationale, synergies and risks. | Each sub-score has a matching `... Rationale` field. AI scoring fields are present only where there is enough data for a reliable assessment. Unscored buyers are still returned with firmographic and financial data. *** ## 6. Examples ### Filtered buyer screen Strategic, publicly listed buyers for Ulteig in the USA and Canada. ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "topic": "Civil Engineering Infrastructure Services", "workflow": "buyer_analysis", "workbook_name": "Ulteig Buyers", "advanced_settings": { "target": "ulteig", "detailed_query": "Engineering and consulting firms seeking to expand infrastructure services", "companies": [], "buyer_type": ["strategic"], "company_type": "public", "geography": ["USA", "CAN"] } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "topic": "Civil Engineering Infrastructure Services", "workflow": "buyer_analysis", "workbook_name": "Ulteig Buyers", "advanced_settings": { "target": "ulteig", "detailed_query": "Engineering and consulting firms seeking to expand infrastructure services", "companies": [], "buyer_type": ["strategic"], "company_type": "public", "geography": ["USA", "CAN"] } } ) print(response.json()["report_id"]) ``` *** # Choosing the right API Source: https://docs.wokelo.ai/choosing-the-right-api ## Overview Wokelo's API suite is organized into two capability groups: **Discovery** and **Workflow Reports**. Use this page to find the right API for your use case. | # | API | Type | Description | | :- | :- | :- | :- | | 1 | Market Map | Async | Ranked company discovery within a market category | | 2 | Target Screening | Async | Scored acquisition targets for a defined acquirer | | 3 | Buyer Screening | Async | Scored buyers for a defined target company | | 4 | Competitor List | Async | Find peers of a given company | | 5 | M\&A Activity | Async | Find M\&A transactions in a defined market | | 6 | Fundraise Activity | Async | Find funding rounds in a defined market | | 7 | Company Research | Async | In-depth company intelligence report | | 8 | Industry Research | Async | End-to-end sector coverage report | | 9 | Peer Comparison | Async | Side-by-side peer benchmarking report | | 10 | Custom Workflow | Async | Build and trigger custom research workflows via API | > [!NOTE] > > All APIs are **Async** and start with `POST /api/workflow_manager/start/`. Each returns a `report_id` immediately. Use `/api/assets/get_notebook_status/` to track completion and `/api/assets/download_report/` to export the results. [Learn how async APIs work →](https://docs.wokelo.ai/how-async-apis-work) *** ## Discovery ### 1. Market Map **Overview:** Search and rank companies across Wokelo's entity graph using custom parameters such as sector, geography, funding stage, revenue range, headcount and keywords. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "agentic_mm"` **What you get:** A ranked, enriched list of companies matching your criteria, each with firmographics, funding data and relevance scoring. **Use Cases:** Deal sourcing, coverage universe building, competitive mapping, BD prospecting, whitespace identification. **Best for:** Situations where you have a thesis or category in mind and need a long list of matching companies to work from. [View API reference →](/market-map-doc) *** ### 2. Target Screening **Overview:** Generate a scored list of acquisition or investment targets for a defined acquirer. Applies Wokelo's entity graph and configurable scoring logic, filtering by sector, geography, headcount, revenue, funding stage and more. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "target_screening_v2"` **What you get:** Ranked targets with rationale, firmographic data, fit scores and filtering metadata. **Use Cases:** Buy-side M\&A screening, platform add-on identification, sector roll-up targeting, investment thesis validation, partnership candidate identification. **Best for:** Structured deal origination workflows where you need a scored, filterable list of candidates matched to a specific acquirer's criteria. [View API reference →](/target-screening-doc) *** ### 3. Buyer Screening **Overview:** Identify potential strategic and financial buyers for a target company. Uses Wokelo's entity graph and scoring logic to surface the most relevant acquirers based on strategic fit, sector overlap and deal profile. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "buyer_analysis"` **What you get:** A ranked buyer list with strategic rationale, buyer type classification (strategic vs. financial) and fit scoring. **Use Cases:** Sell-side M\&A process preparation, exit planning, fundraising target identification, secondary sale preparation. **Best for:** Sell-side advisors and founders looking to build a qualified buyer universe quickly, particularly early in a process. [View API reference →](/buyer-screening-doc) *** ### 4. Competitor List **Overview:** Discover companies similar to a given company, filtered by geography, funding stage, headcount, financials and more. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "company_peers"` **What you get:** A list of peer companies with firmographic data, similarity scoring and commentary. **Use Cases:** Competitive benchmarking, peer set construction, deal sourcing, coverage universe building, comparable company analysis. **Best for:** Quickly building a peer set or competitive landscape for a given company without manually curating lists. [View API reference →](/competitor-list-doc) *** ### 5. M\&A Activity **Overview:** Surface the M\&A transactions that have taken place in a defined industry domain, with intelligence on deal amounts, acquirer and target profiles, deal status and news context. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "acquisition_workflow"` **What you get:** A structured set of M\&A transactions for your market, filterable by transaction date, status and amount, as well as by target geography, company type, funding stage and headcount. **Use Cases:** Tracking acquirer behavior, sourcing acquisition targets, competitive intelligence on M\&A patterns, precedent transaction research, deal origination. **Best for:** Situations where you need to understand how actively a market is consolidating, who the active acquirers are, and what kinds of targets are being acquired. [View API reference →](/acquisitions-doc) *** ### 6. Fundraise Activity **Overview:** Surface the funding rounds that have taken place in a defined industry domain, with intelligence on round stage, amount, investors and company profiles. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "fundraisers_workflow"` **What you get:** A structured set of funding rounds for your market, filterable by transaction date, round type and amount, as well as by company geography, company type and headcount. **Use Cases:** Investor research, tracking funding activity in a sector, identifying recently funded companies as potential targets or partners, monitoring portfolio company fundraising, sourcing for outreach. **Best for:** Situations where you want to see who is raising capital in a market, from which investors, and at what stage. [View API reference →](/fundraise-doc) *** ## Workflow Reports Workflow APIs generate full-length research reports. Like all Wokelo APIs, they are asynchronous and return a `report_id` that you use to track status and download results. ### 7. Company Research **Overview:** Generate a comprehensive company intelligence report covering 19 sections including firmographics, products and services, strategic moves, management profiles, financials, funding history, competitive landscape and alternative signals. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "company_primer"` **What you get:** A structured JSON report with the following sections: `Quick Snapshot` · `Executive Summary` · `Product insights` · `Transaction highlights` · `Strategic moves and news` · `Earnings call highlights` · `Annual report highlights` · `Customer and business insights` · `Financial summary` · `Ownership structure` · `Management profiles` · `Headcount and hiring trends` · `Competitive landscape` · `Wokelo insights` · `Web and social footprint` · `Market insights` · `Annexure` · `meta` · `qna` **Use Cases:** Target deep-dives, investment memo inputs, client briefings, IC memo preparation, LP reporting. **Best for:** Situations where you need a complete, structured intelligence package on a company, replacing hours of manual research with a single API call. *** ### 8. Industry Research **Overview:** Generate a comprehensive sector coverage report covering market structure, deal activity, partnerships, market sizing, competitive landscape, regulatory environment, case studies and more. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "industry_research"` **What you get:** A structured JSON report spanning market overview, key players, competitive dynamics, deal trends, regulations and thematic signals. **Use Cases:** Market entry analysis, client engagements, thematic research, fund thesis validation, new vertical entry, sector coverage initiation. **Best for:** Situations where you need end-to-end sector intelligence, from sizing and structure to competitive dynamics and regulatory signals, in a single report. *** ### 9. Peer Comparison **Overview:** Benchmark up to 5 companies side-by-side across key business and financial dimensions. Generates a structured comparison report with custom parameters. **Endpoint:** `POST /api/workflow_manager/start/` with `"workflow": "peer_comparison"` **What you get:** A structured comparison report covering product positioning, financials, headcount, funding, strategic priorities and competitive differentiation across all input companies. **Use Cases:** Competitive benchmarking, portfolio benchmarking, relative value analysis, IC presentation inputs. **Best for:** Diligence and coverage workflows where you need a structured, side-by-side view of multiple companies, replacing manual comparison grids. *** ### 10. Custom Workflow **Overview:** Build a custom research workflow in Wokelo's no-code agent builder, applying your own frameworks, section templates and analytical methodologies, then trigger it via API in supported output formats (JSON, DOCX, PDF). **Endpoint:** `POST /api/workflow_manager/start/` with your custom `"workflow"` identifier **What you get:** Output in your configured format, following your defined structure and analytical framework. Supports Wokelo's full intelligence stack as underlying data sources. **Use Cases:** Repeatable internal research, custom client deliverables, proprietary scoring models, white-label research delivery, automated report generation pipelines. **Best for:** Teams with established research frameworks who want to automate report generation at scale, without being constrained to Wokelo's default report templates. # Company Research Source: https://docs.wokelo.ai/company-research POST https://api.wokelo.ai/api/workflow_manager/start/ ## Overview Starts generating a Company Research report for a specific company. ## Endpoint Details * **Method:** POST * **Endpoint:** `/api/workflow_manager/start/` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request ### Request Parameters #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request #### Body Parameters **industry** `string` Company's industry. If not provided, Wokelo will auto-detect the industry **permalink** `string` *required* Crunchbase permalink of the company **website** `string` *required* website of the company **workflow** `string` *required* `company_primer` **custom\_files** `array of objects` Files to include in the report. Use `fileName` values from the file upload response *Note: Either of company's permalink or website is required for the company-based workflows* ## Response Successful response will include the report\_id of the Company Research report #### Successful Response Fields **report\_id** `integer` Report id for the initiated Company Research report ```json 200 theme={"system"} { "report_id": 123345 } ``` # Company Research Source: https://docs.wokelo.ai/company-research-doc Generate a comprehensive, source-cited company intelligence report — covering firmographics, executive summary, key insights, product portfolio, and M&A activity — as a structured JSON, PDF, DOCX, or PPT deliverable. ## 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](/supporting-apis-doc#report-status) endpoint and retrieve the finished report using the [Download Report](/supporting-apis-doc#download-report) endpoint. **The three-step workflow:** ```text theme={"system"} Step 1: POST /api/workflow_manager/start/ → returns report_id Step 2: GET /api/assets/get_notebook_status/ → poll until status = "Completed" Step 3: POST /api/assets/download_report/ → retrieve JSON / PDF / DOCX / PPT ``` 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 > [!NOTE] > > 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](/how-async-apis-work) for a full explanation of the polling lifecycle. *** ## 2. Quick Start **Step 1 — Submit the report request** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "company_primer", "permalink": "salesforce" }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "workflow": "company_primer", "permalink": "salesforce" } ) report_id = response.json()["report_id"] print(f"Report submitted. report_id: {report_id}") ``` **Step 2 — Poll for completion** ```python theme={"system"} import time def wait_for_report(report_id, api_key, poll_interval=15, timeout=600): headers = {"Authorization": f"Bearer {api_key}"} elapsed = 0 while elapsed < timeout: r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=headers, params={"report_id": report_id} ) status = r.json().get("status", "") print(f"[{elapsed}s] Status: {status}") if status == "Completed": return True if status == "Failed": raise Exception(f"Report {report_id} failed") time.sleep(poll_interval) elapsed += poll_interval raise TimeoutError(f"Report {report_id} did not complete within {timeout}s") wait_for_report(report_id, api_key="") ``` **Step 3 — Download the report** ```python theme={"system"} # Fetch as JSON for programmatic processing result = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers={"Authorization": "Bearer "}, json={"report_id": report_id, "file_type": "json"} ) report = result.json() # Or download as a formatted document pdf_result = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers={"Authorization": "Bearer "}, json={"report_id": report_id, "file_type": "pdf"} ) with open("company_research.pdf", "wb") as f: f.write(pdf_result.content) ``` *** ## 3. Authentication All requests must include a **Bearer token** in the `Authorization` HTTP header. ```text theme={"system"} Authorization: Bearer ``` 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](mailto:support@wokelo.ai) if you do not yet have API access. > [!WARNING] > > 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** ```text theme={"system"} POST https://api.wokelo.ai/api/workflow_manager/start/ ``` All parameters are passed as JSON in the request body. | Parameter | Type | Required | Description | | - | - | - | - | | `workflow` | string | **Required** | Must always be `"company_primer"`. This fixed value tells Wokelo's workflow engine to run the Company Research report. | | `permalink` | string | Required\* | Wokelo/Crunchbase permalink of the company (e.g. `"salesforce"`, `"tesla-motors"`). Use the [Company Search API](/supporting-apis-doc#company-search) to look up a company's permalink by name. | | `website` | string | Required\* | Full URL of the company's website (e.g. `"https://www.salesforce.com"`). Accepted as an alternative to `permalink` when the permalink is unknown. | | `industry` | string | Optional | Company's industry vertical. If omitted, Wokelo auto-detects the industry from its knowledge base. Providing this speeds up processing and can improve industry-specific framing in the report. | | `workbook_name` | string | Optional | Label for the generated report workbook. Defaults to the company name if omitted. | | `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](/supporting-apis-doc#file-upload). Use this to incorporate CIMs, management presentations, or internal diligence notes. | > [!NOTE] > > 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:** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "company_primer", "permalink": "salesforce", "industry": "Enterprise Software & Cloud", "workbook_name": "Salesforce Q2 2026 Research" }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "workflow": "company_primer", "permalink": "salesforce", "industry": "Enterprise Software & Cloud", "workbook_name": "Salesforce Q2 2026 Research" } ) print(response.json()) # {"report_id": 123345} ``` *** ## 5. Response ### Submission response The initial POST returns immediately with a single field: ```json theme={"system"} { "report_id": 123345 } ``` | Field | Type | Description | | - | - | - | | `report_id` | integer | Unique identifier for this report job. Use it with the Report Status and Download Report endpoints to track and retrieve the completed report. Store this value — it is the only handle to your report. | ### Report status response Poll `GET /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 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_details` — `product_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 services` — `product_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 initiatives` — `released_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 map` — `m_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 Strategy` — `acquisitions` 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` > [!NOTE] > > 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. | `file_type` | Description | | - | - | | `"json"` | Fully structured JSON — all sections, fields, and source citations. Best for programmatic processing, CRM ingestion, or downstream pipelines. | | `"pdf"` | Formatted PDF report with charts, tables, and narrative sections. Best for sharing with stakeholders. | | `"docx"` | Editable Word document. Best for teams that customise reports before distribution. | | `"ppt"` | PowerPoint presentation with section slides. Best for IC presentations and LP updates. | *** ## 6. Examples ### Basic company research — by permalink The most common pattern: look up the permalink, submit, poll, and download JSON. ```bash cURL theme={"system"} # Step 1: Submit curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{"workflow": "company_primer", "permalink": "salesforce"}' # Step 2: Poll (replace 123345 with your report_id) curl --location 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=123345' \ --header 'Authorization: Bearer ' # Step 3: Download curl --location 'https://api.wokelo.ai/api/assets/download_report/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{"report_id": 123345, "file_type": "json"}' ``` ```python Python theme={"system"} import requests, time API_KEY = "" HEADERS = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } # Step 1: Submit submit = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={"workflow": "company_primer", "permalink": "salesforce"} ) report_id = submit.json()["report_id"] print(f"Submitted. report_id: {report_id}") # Step 2: Poll while True: status_r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=HEADERS, params={"report_id": report_id} ) status = status_r.json().get("status") print(f"Status: {status}") if status == "Completed": break if status == "Failed": raise Exception("Report failed") time.sleep(15) # Step 3: Download result = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers=HEADERS, json={"report_id": report_id, "file_type": "json"} ) report = result.json() print(f"Sections: {list(report.keys())}") ``` **Sample submission response:** ```json theme={"system"} { "report_id": 123345 } ``` ### Using a website URL instead of a permalink When the company's permalink is unknown or unavailable, pass the full website URL. ```python theme={"system"} response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={ "workflow": "company_primer", "website": "https://www.stripe.com" } ) report_id = response.json()["report_id"] ``` ### Resolving a permalink via Company Search before submitting Use the Company Search API to find a company's permalink by name, then pass it to Company Research. ```python theme={"system"} # Search for the company search = requests.get( "https://api.wokelo.ai/api/enterprise/company/search", headers=HEADERS, params={"query": "HubSpot", "search_by": "name", "company_type": "all"} ) permalink = search.json()["data"][0]["permalink"] # e.g. "hubspot" # Submit research report submit = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={"workflow": "company_primer", "permalink": permalink} ) report_id = submit.json()["report_id"] print(f"Research for {permalink} started. report_id: {report_id}") ``` ### Batch research on a watchlist Submit Company Research for multiple companies concurrently, then collect all reports once completed. ```python theme={"system"} import requests, time, concurrent.futures API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} COMPANIES = ["salesforce", "hubspot", "pipedrive", "zoho", "freshworks"] def submit_research(permalink): r = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={"workflow": "company_primer", "permalink": permalink} ) return permalink, r.json()["report_id"] def poll_until_done(report_id, interval=20, timeout=900): elapsed = 0 while elapsed < timeout: r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=HEADERS, params={"report_id": report_id} ) status = r.json().get("status") if status == "Completed": return True if status == "Failed": return False time.sleep(interval) elapsed += interval return False def fetch_report(report_id): r = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers=HEADERS, json={"report_id": report_id, "file_type": "json"} ) return r.json() # Submit all concurrently with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool: futures = {pool.submit(submit_research, c): c for c in COMPANIES} jobs = {} for future in concurrent.futures.as_completed(futures): permalink, report_id = future.result() jobs[permalink] = report_id print(f"Submitted: {permalink} → report_id {report_id}") # Poll and collect reports = {} for permalink, report_id in jobs.items(): ok = poll_until_done(report_id) if ok: reports[permalink] = fetch_report(report_id) print(f"Collected: {permalink}") else: print(f"Failed or timed out: {permalink}") print(f"\nCollected {len(reports)} / {len(COMPANIES)} reports") ``` ### 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. ```python theme={"system"} import requests API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}"} # Step 1: Upload the file with open("target_company_cim.pdf", "rb") as f: upload_r = requests.post( "https://api.wokelo.ai/api/assets/upload/", headers=HEADERS, files={"files": ("target_company_cim.pdf", f, "application/pdf")} ) file_name = upload_r.json()["fileName"] # unique file identifier # Step 2: Submit report referencing the uploaded file submit_r = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={**HEADERS, "Content-Type": "application/json"}, json={ "workflow": "company_primer", "permalink": "target-company-permalink", "custom_files": [{"fileName": file_name}] } ) report_id = submit_r.json()["report_id"] print(f"Report with custom file submitted. report_id: {report_id}") ``` ### Extracting specific sections from the JSON report Work with individual sections of the downloaded JSON for targeted downstream processing. ```python theme={"system"} # Assume report is already downloaded as a dict report = fetch_report(report_id) # --- Quick Snapshot --- snapshot = report["Quick Snapshot"]["Quick Snapshot"]["quick_snapshot"] firmograph = snapshot["company_firmographics"]["details"] financials = firmograph["financials"] print(f"Company: {snapshot['company_firmographics']['organization']['name']}") print(f"HQ: {firmograph['hq']}") print(f"Employees: {firmograph['employees_in_linkedin']:,}") print(f"Revenue: ${financials['revenue']['value'] / 1e9:.1f}B ({financials['revenue']['period']})") print(f"Market Cap: ${financials['market_cap']['value'] / 1e9:.1f}B") # --- Key Insights (headlines only) --- insights = report["Executive Summary"]["Key Insights"]["key_insights"] print(f"\nKey Insights ({len(insights)} total):") for i, card in enumerate(insights, 1): print(f" {i}. {card['insight']['title']}") # --- Recent M&A (2024+) --- timeline = report["Transaction highlights"]["M&A Strategy"]["acquisitions"]["m_and_a_timeline"] recent_ma = [t for t in timeline if int(t["acquisition_date"][:4]) >= 2024] print(f"\nAcquisitions since 2024: {len(recent_ma)}") for t in recent_ma: amt = t["acquisition_amount"] amt_str = f"${amt / 1e9:.1f}B" if isinstance(amt, float) and amt > 0 else "undisclosed" print(f" {t['acquisition_date'][:10]} {t['company']['organization']['name']} ({amt_str})") # --- Product areas --- products = report["Product insights"]["Product and services"]["products_and_services"] print(f"\nProduct areas ({len(products)}):") for area in products: titles = [p["title"] for p in area["details"]] print(f" {area['product_area']}: {', '.join(titles)}") ``` ### Exporting a PPT for IC review ```python theme={"system"} import requests HEADERS = {"Authorization": "Bearer "} ppt_r = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers=HEADERS, json={"report_id": 123345, "file_type": "ppt"} ) with open("salesforce_research.pptx", "wb") as f: f.write(ppt_r.content) print("Saved salesforce_research.pptx") ``` *** ## 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. | Status | Meaning | Cause & Resolution | | - | - | - | | `200 OK` | Request accepted | `report_id` returned. Proceed to polling. | | `400 Bad Request` | Invalid parameters | Missing `workflow` value, missing both `permalink` and `website`, or an unrecognised `workflow` string. 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 endpoint or to this company. Contact [support@wokelo.ai](mailto:support@wokelo.ai). | | `404 Not Found` | Company not found | The `permalink` could not be resolved. Use the [Company Search API](/supporting-apis-doc#company-search) to verify, or switch to `website`. | | `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](mailto:support@wokelo.ai). | **Handling a `"Failed"` report status:** ```python theme={"system"} status_r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=HEADERS, params={"report_id": report_id} ) data = status_r.json() if data.get("status") == "Failed": print(f"Report {report_id} failed.") # Resubmit with the same parameters resubmit = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={"workflow": "company_primer", "permalink": "salesforce"} ) new_report_id = resubmit.json()["report_id"] print(f"Resubmitted. New report_id: {new_report_id}") ``` **Retry with exponential back-off on submission:** ```python theme={"system"} import time, requests def submit_with_retry(body, api_key, max_retries=3): headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } for attempt in range(max_retries): try: r = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=headers, json=body, timeout=30 ) if r.status_code == 429: time.sleep(2 ** attempt) continue r.raise_for_status() return r.json()["report_id"] except requests.exceptions.Timeout: if attempt == max_retries - 1: raise time.sleep(1) raise Exception(f"Submission failed after {max_retries} attempts") ``` *** ## 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](/supporting-apis-doc#company-search) to resolve a company name to its permalink before submitting: ```python theme={"system"} search = requests.get( "https://api.wokelo.ai/api/enterprise/company/search", headers=HEADERS, params={"query": "OpenAI", "search_by": "name"} ) permalink = search.json()["data"][0]["permalink"] ``` **`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: ```python theme={"system"} # Recommended polling pattern for wait in [15, 15, 30, 30, 60, 60, 120]: # seconds time.sleep(wait) status = get_status(report_id) if status in ("Completed", "Failed"): break ``` **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: ```python theme={"system"} json={ "workflow": "company_primer", "permalink": "some-niche-startup", "industry": "Climate Technology & Carbon Markets" } ``` **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](/supporting-apis-doc#file-upload) 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: ```python theme={"system"} # ❌ Will throw TypeError when amount is "" formatted = f"${deal['acquisition_amount'] / 1e9:.1f}B" # ✅ Safe — check type first amt = deal.get("acquisition_amount") formatted = f"${amt / 1e9:.1f}B" if isinstance(amt, (int, float)) and amt > 0 else "Undisclosed" ``` **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. *** ## 9. Related APIs > **[Company Instant Enrichment](/company-instant-enrichment-doc)** > > Synchronous firmographic enrichment — returns structured company data immediately without a report generation step. > **[Company Deep Intelligence](/company-deep-intelligence-doc)** > > Deeper async intelligence on strategy, financials, and competitive positioning — more granular than Company Research. > **[Industry Research](/industry-research-doc)** > > Run the same async workflow pattern against an industry or sector instead of a specific company. > **[Peer Comparison](/peer-comparison-doc)** > > Generate a structured comparison of two or more companies across key dimensions in a single report. > **[Company News Monitoring](/company-news-monitoring-doc)** > > Fetch real-time, source-cited news articles for any company — synchronous, no polling required. > **[Supporting APIs](/supporting-apis-doc)** > > Company Search, File Upload, Report Status, and Download Report — all used alongside Company Research. # Company Search Source: https://docs.wokelo.ai/company-search GET /api/enterprise/company/search Search for companies using name, website, or ticker. Returns a list of companies with their permalink and other attributes. ## Overview Search for companies using name, website or ticker. It returns a list of companies with their permalink and other attributes. ## Endpoint Details * **Method:** GET * **Endpoint:** `/api/enterprise/company/search` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request #### URL Parameters **query** `string` *required* The search query string (e.g., company name, website or ticker). Examples: Tesla OR `https://tesla.com` OR TSLA **search\_by** `string` Field to search by. Supported value: `name`, `website`, `ticker` **company\_type** `string` Filter by company type. Supported values: `private`, `public`, `all` Note: Use `all` to return all types. (This is the default value is nothing is mentioned) ## Response **Successful Response Fields** Returns a JSON object with the following structure: **status** `string` `"success"` if the request was processed successfully. **data** `array` List of matching company objects. **count** `integer` Total number of results returned. **Company Object Fields** | Field | Description | | - | - | | `name` | Company name. | | `permalink` | Unique identifier/slug for the company. | | `short_description` | Brief description of the company. | | `founded_year` | Year the company was founded. | | `ipo_status` | IPO status (e.g., `private`, `public`). | | `hq` | Headquarters location. | | `industries` | Industry or sector the company operates in. | | `website` | Company website URL. | | `ticker` | Stock ticker symbol (if applicable). | | `country_code` | ISO country code. | | `country` | Full country name. | | `domain` | Company domain name. | | `last_funding_round` | Most recent funding round (e.g., `Seed`, `Pre Seed` etc) | **Sample Response** ```json theme={"system"} { "status": "success", "data": [ { "name": "Wokelo AI", "permalink": "wokelo-ai", "short_description": "Wokelo builds purpose-built AI agents for dealmaking and consulting, designed by domain-experts to power sourcing, diligence and strategy.", "founded_year": "2023", "ipo_status": "private", "hq": "Seattle, United States", "industries": "AI Investment Research Platform", "website": "https://www.wokelo.ai/", "ticker": "", "country_code": "US", "country": "United States", "domain": "wokelo.ai", "last_funding_round": "Seed" } ], "count": 10 } ``` ```json 200 theme={"system"} { "status": "success", "data": [ { "name": "Wokelo AI", "permalink": "wokelo-ai", "short_description": "Wokelo builds purpose-built AI agents for dealmaking and consulting.", "founded_year": "2023", "ipo_status": "private", "hq": "Seattle, United States", "industries": "AI Investment Research Platform", "website": "https://www.wokelo.ai/", "ticker": "", "country_code": "US", "country": "United States", "domain": "wokelo.ai", "last_funding_round": "Seed" } ], "count": 10 } ``` # Competitor List Source: https://docs.wokelo.ai/competitor-enrich POST https://api.wokelo.ai/api/workflow_manager/start/ ## Overview The Competitor List API generates a long list of companies similar to a given company, enriched with structured data. You can refine the output with a detailed query, sample companies, geography, company type, employee count, funding stage, financial filters, and more. Competitor List runs as a workflow. Set `workflow` to `company_peers` in the request body to start one. The request returns a `report_id`, which you then use to track completion and export the results. ## Endpoint Details * Method: POST * Endpoint: `/api/workflow_manager/start/` ## Authentication Requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request ### Body Parameters **workflow** `string` *required* The workflow to run. Must be `"company_peers"` for Competitor List. **workbook\_name** `string` *required* Name of the workbook that will hold the generated competitor list (e.g. `"LegalTech Players"`) **permalink** `string` *required* Permalink or complete URL of the company whose peers need to be found (e.g. `"harvey-128b"` OR `"https://www.harvey.ai/"`) **advanced\_settings** `object` Filter parameters object. All filters live inside `advanced_settings`. Include the object in every request, and send empty values (`""`, `[]`) for any filter you do not want to apply. **detailed\_query** `string` A more descriptive query to refine the search scope. **companies** `string[]` Permalinks of representative companies or their complete URLs to anchor the competitor search. **geography** `string[]` Geographic scope. Pass `["Worldwide"]` for no geographic restriction, or a list of ISO country codes (e.g. `["USA", "GBR"]`). **company\_type** `string` Type of company to include. Accepted values: `"private"`, `"public"`, `"all"` **employee\_count** `string[]` Filter by employee headcount range. Pass an empty array to include all headcounts. Supported array values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+` **founded\_year** `object` Filter by company founding year. **from** `integer` Minimum founding year (inclusive), e.g. `2010` **to** `integer` Maximum founding year (inclusive), e.g. `2020` **funding\_stage** `string[]` Filter by funding stage (e.g. `"Series A"`, `"Series B"`). Pass an empty array to include all stages. Supported array values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A`, `Series B`, `Series C`, `Series D`, `Series E`, `Series F`, `Series G`, `Series H`, `Series I`, `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others` **total\_funding** `object` Filter by total funding amount raised (in USD). **from** `number` Minimum total funding in USD, e.g. `1000000` **to** `number` Maximum total funding in USD, e.g. `50000000` **total\_funding\_include\_blanks** `boolean` When `true`, companies with no reported total funding are included in the results alongside companies that match the `total_funding` range. **last\_funding\_round** `object` Filter by last funding round amount (in USD). **from** `number` Minimum last funding round in USD, e.g. `500000` **to** `number` Maximum last funding round in USD, e.g. `20000000` **revenue** `object` Filter by annual revenue (in USD). **from** `number` Minimum annual revenue in USD, e.g. `500000` **to** `number` Maximum annual revenue in USD, e.g. `10000000` **ebitda** `object` Filter by EBITDA (in USD). **from** `number` Minimum EBITDA in USD **to** `number` Maximum EBITDA in USD **net\_income** `object` Filter by net income (in USD). **from** `number` Minimum net income in USD **to** `number` Maximum net income in USD **ev\_ebitda** `object` Filter by EV/EBITDA multiple. **from** `number` Minimum EV/EBITDA multiple **to** `number` Maximum EV/EBITDA multiple ```json Basic request theme={"system"} { "workflow": "company_peers", "workbook_name": "LegalTech Players", "permalink": "harvey-128b", "advanced_settings": { "detailed_query": "", "companies": [], "company_type": "all", "geography": ["Worldwide"], "employee_count": [], "funding_stage": [], "total_funding_include_blanks": true } } ``` ```json Request with filters theme={"system"} { "workflow": "company_peers", "workbook_name": "LegalTech Players", "permalink": "harvey-128b", "advanced_settings": { "detailed_query": "AI-powered legal research and drafting platforms", "companies": [], "company_type": "private", "geography": ["USA", "GBR"], "employee_count": ["51-100", "101-250"], "funding_stage": ["Series A", "Series B"], "total_funding": { "from": 1000000, "to": 50000000 }, "total_funding_include_blanks": false } } ``` ### Response A successful response returns a `report_id` that identifies the competitor list report. #### Successful Response Fields **report\_id** `integer` Unique identifier for the report created by this request. Use it to track completion and to download the results (see below). ```json 200 theme={"system"} { "report_id": 117253 } ``` ## Tracking Completion and Exporting Results Competitor List generation is asynchronous. After you receive a `report_id`: 1. Use `/api/assets/get_notebook_status/` to track completion of the report. 2. Once the report is complete, use `/api/assets/download_report/` to export the results. # Competitor List Source: https://docs.wokelo.ai/competitor-list-doc Generate a ranked list of companies similar to a given seed company. ## 1. Overview The Competitor List API generates a ranked list of companies similar to a given seed company, enriched with firmographic, funding and financial data. Given a company permalink and optional refinements, the AI pipeline evaluates each candidate against the seed company's product, customers and business model. Unlike [Market Map](/market-map-doc), which starts from a market topic, Competitor List starts from a specific company. This is an **asynchronous API**. Starting the workflow returns a `report_id`, which you use to track completion and export the results. See [How Async APIs work](/how-async-apis-work). Each peer includes firmographics, product profile, funding and headcount, financials (for public companies), M\&A history, an `Overall Score` (1 to 10) measuring similarity to the seed company, and a `Commentary` explaining the overlap. **Common use cases:** * **Competitive intelligence**: build a vendor landscape around a specific company * **Peer benchmarking**: identify comparables for valuation or KPI analysis * **Roll-up sourcing**: find players similar to a platform company for bolt-on consolidation *** ## 2. Quick Start **Step 1: Start the workflow** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "company_peers", "workbook_name": "LegalTech Players", "permalink": "harvey-128b", "advanced_settings": { "detailed_query": "", "companies": [], "company_type": "all", "geography": ["Worldwide"], "employee_count": [], "funding_stage": [], "total_funding_include_blanks": true } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "workflow": "company_peers", "workbook_name": "LegalTech Players", "permalink": "harvey-128b", "advanced_settings": { "detailed_query": "", "companies": [], "company_type": "all", "geography": ["Worldwide"], "employee_count": [], "funding_stage": [], "total_funding_include_blanks": True } } ) print(response.json()["report_id"]) ``` The response contains a `report_id`. **Step 2: Track completion** Use `/api/assets/get_notebook_status/` with the `report_id` to check whether the report has completed. **Step 3: Export results** Once the report is complete, use `/api/assets/download_report/` with the `report_id` to export the results. *** ## 3. Authentication Include a Bearer token in the `Authorization` header of every request. ```text theme={"system"} Authorization: Bearer ``` Obtain a token from the `/auth/token/` endpoint using the client id and client secret under **Account Details → API Credentials** in the Wokelo dashboard. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access. > [!WARNING] > > Never expose your token in client-side code or public repositories. *** ## 4. Request Reference **Endpoint** ```text theme={"system"} POST https://api.wokelo.ai/api/workflow_manager/start/ ``` The request body is JSON. Include `advanced_settings` in every request and send empty values (`""`, `[]`) for filters you do not want to apply. | Parameter | Type | Required | Description | | - | - | - | - | | `workflow` | string | **Required** | Must be `"company_peers"`. | | `workbook_name` | string | **Required** | Name of the workbook that holds the generated report. | | `permalink` | string | **Required** | Permalink or full URL of the seed company whose peers you want to find (e.g. `"harvey-128b"`). | | `advanced_settings` | object | Optional | Filter parameters. All filters below live inside this object. | | `advanced_settings.detailed_query` | string | Optional | A descriptive query that refines what "similar" means for this run. | | `advanced_settings.companies` | string\[] | Optional | Permalinks or full URLs of additional representative companies to anchor the peer set. | | `advanced_settings.geography` | string\[] | Optional | `["Worldwide"]` for no restriction, or ISO country codes (e.g. `["USA", "GBR"]`). | | `advanced_settings.company_type` | string | Optional | `"private"`, `"public"` or `"all"`. | | `advanced_settings.employee_count` | string\[] | Optional | Headcount bands. Empty array includes all. Values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+`. | | `advanced_settings.founded_year` | object | Optional | Object with `from` and/or `to` (integer years, inclusive). | | `advanced_settings.funding_stage` | string\[] | Optional | Empty array includes all. Values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A` to `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others`. | | `advanced_settings.total_funding` | object | Optional | Object with `from` and/or `to`, in USD. | | `advanced_settings.total_funding_include_blanks` | boolean | Optional | When `true`, companies with no reported total funding are included. | | `advanced_settings.last_funding_round`, `.revenue`, `.ebitda`, `.net_income` | object | Optional | Each accepts `from` and/or `to`, in USD. Revenue, EBITDA and net income work best with `company_type: "public"`. | | `advanced_settings.ev_ebitda` | object | Optional | Object with `from` and/or `to` (EV/EBITDA multiple). | *** ## 5. Response ### Workflow start response ```json theme={"system"} { "report_id": 117253 } ``` | Field | Type | Description | | - | - | - | | `report_id` | integer | Unique identifier of the report. Use it to track completion and export results. | ### Report output fields | Field | Description | | - | - | | `Permalink`, `Name`, `Website` | Wokelo company identifier, display name and primary domain. | | `HQ City`, `HQ Country`, `HQ Continent`, `Founded` | Headquarters location and founding year. | | `Type`, `Operating Status` | Ownership type (`Public` or `Private`) and status (e.g. `Operating`, `Acquired`, `IPO`). | | `Product Category`, `Core Offering`, `Product Catalog` | Primary product category, AI-generated description of the core business, and key products. | | `Employees (Crunchbase)`, `Employees (LinkedIn)` | Headcount band and numeric headcount. | | `Funding Stage`, `Total Funding`, `Last Funding Date`, `Key Investors` | Funding profile. Total funding is in USD. Typically empty for public companies. | | `Revenue`, `EBITDA`, `Net Income`, `Market Cap`, `Enterprise Value`, `Ticker`, margins and multiples | Financial data in USD, primarily populated for public companies. | | `Acquisitions`, `Investments` | Past acquisitions (with year) and notable investments. May be empty. | | `Overall Score`, `Commentary` | Similarity to the seed company (1 to 10), and an AI-written explanation of the overlap and differences. | *** ## 6. Examples ### Filtered peer set Private AI legal technology peers of Harvey in the USA and UK, 51 to 250 employees, Series A or B, with \$1M to \$50M total funding. ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "company_peers", "workbook_name": "LegalTech Players", "permalink": "harvey-128b", "advanced_settings": { "detailed_query": "AI-powered legal research and drafting platforms", "companies": [], "company_type": "private", "geography": ["USA", "GBR"], "employee_count": ["51-100", "101-250"], "funding_stage": ["Series A", "Series B"], "total_funding": { "from": 1000000, "to": 50000000 }, "total_funding_include_blanks": false } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "workflow": "company_peers", "workbook_name": "LegalTech Players", "permalink": "harvey-128b", "advanced_settings": { "detailed_query": "AI-powered legal research and drafting platforms", "companies": [], "company_type": "private", "geography": ["USA", "GBR"], "employee_count": ["51-100", "101-250"], "funding_stage": ["Series A", "Series B"], "total_funding": { "from": 1000000, "to": 50000000 }, "total_funding_include_blanks": False } } ) print(response.json()["report_id"]) ``` *** # Contact Source: https://docs.wokelo.ai/contact Get in touch with Wokelo Start Building with \ Wokelo APIs ================= Access AI-native APIs designed for your agentic workflows and tools without the overhead of legacy data infrastructure. Trusted by Industry Leaders Trusted by Industry Leaders # Credit Balance Source: https://docs.wokelo.ai/credit-balance GET /api/wkl/credits/get-credits-balance/ ## Overview Retrieves the current credit balance for your account, along with the total credits allotted and the account's expiry period. ## Endpoint Details * **Method:** GET * **Endpoint:** `/api/wkl/credits/get-credits-balance/` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request ### Request Parameters #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request **Content-Type** `string` *required* Must be set to `application/json` This endpoint takes no URL or body parameters. ## Response Successful response will include the `credits_consumed`, `acount_expiry_period`, `credits_balance`, and `total_credits` fields. **Sample Response** ```json theme={"system"} { "credits_consumed": 0, "acount_expiry_period": "2099-10-04T09:11:05Z", "credits_balance": 849.2029999999613, "total_credits": 25000.0 } ``` **Response Fields** | Field | Type | Description | | - | - | - | | `credits_consumed` | number | Credits consumed by this API call itself (typically `0`). | | `acount_expiry_period` | string | Expiry timestamp (ISO 8601) for the current credit allotment/plan. | | `credits_balance` | number | Credits | # Credit Logs Source: https://docs.wokelo.ai/credit-balance-1 GET /api/wkl/credits/get-credits-logs/ ## Overview Retrieves a paginated log of credit-consuming activity across your account, including reports, newsletters, API calls, and Assistant usage. ## Endpoint Details * **Method:** GET * **Endpoint:** `/api/wkl/credits/get-credits-logs/` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request ### Request Parameters #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request **Content-Type** `string` *required* Must be set to `application/json` #### Query Parameters **page** `integer` Page number to retrieve. Defaults to `1`. Example: `1` **page\_size** `integer` Number of log entries to return per page. Example: `30` ## Response Successful response will include the `count`, `current_page`, `total_pages`, `data`, and `credits_consumed` fields. **Sample Response** ```json theme={"system"} { "count": 2604, "current_page": 1, "total_pages": 87, "data": [ { "id": 2681, "email": "system@wokelo.ai", "date": "2026-07-21T11:05:15.040079+00:00", "name": "Newsletter Pipeline", "type": "Report", "sub_info": "Newsfeed", "credit_consumed": 10.0 }, { "id": 2670, "email": "rahul.parlani@wokelo.ai", "date": "2026-07-17T14:04:16.175945+00:00", "name": "Arbor Memorial Inc. - Add Company", "type": "API", "sub_info": "Add Company", "credit_consumed": 0.0 } ], "credits_consumed": 0 } ``` **Response Fields** | Field | Type | Description | | - | - | - | | `count` | integer | Total number of log entries across all pages. | | `current_page` | integer | The page number returned in this response. | | `total_pages` | integer | Total number of pages available. | | `data` | array | List of individual credit log entries (see below). | | `credits_consumed` | number | Credits consumed by this logging call itself (typically `0`). | **Log Entry Fields** | Field | Type | Description | | - | - | - | | `id` | integer | Unique identifier for the log entry. | | `email` | string | Email of the user who triggered the activity. May be blank for system-generated entries (e.g. scheduled newsletters). | | `date` | string | Timestamp (ISO 8601) of the activity. | | `name` | string | Name of the report, notebook, or task associated with the activity. | | `type` | string | Category of activity. Observed values include `Report`, `Newsletter`, `API`, and `Assistant`. | | `sub_info` | string | Additional context on the specific action taken (e.g. `Add Company`, `Research Plan Validation`, `Newsfeed`). | | `credit_consumed` | number | Credits consumed by this specific activity. | ```json 200 theme={"system"} { "count": 2604, "current_page": 1, "total_pages": 87, "data": [ { "id": 2663, "email": "tarun@wokelo.ai", "date": "2026-07-16T15:29:37.451531+00:00", "name": "Acquisition Target Companies", "type": "Assistant", "sub_info": "generated via deep_research, final summary layer cost", "credit_consumed": 10.0 } ], "credits_consumed": 0 } ``` # Credit Logs Source: https://docs.wokelo.ai/credit-logs GET /api/wkl/credits/get-credits-logs/ ## Overview Retrieves a paginated log of credit-consuming activity across your account, including reports, newsletters, API calls, and Assistant usage. ## Endpoint Details * **Method:** GET * **Endpoint:** `/api/wkl/credits/get-credits-logs/` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request ### Request Parameters #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request **Content-Type** `string` *required* Must be set to `application/json` #### Query Parameters **page** `integer` Page number to retrieve. Defaults to `1`. Example: `1` **page\_size** `integer` Number of log entries to return per page. Example: `30` ## Response Successful response will include the `count`, `current_page`, `total_pages`, `data`, and `credits_consumed` fields. **Sample Response** ```json theme={"system"} { "count": 2604, "current_page": 1, "total_pages": 87, "data": [ { "id": 2681, "email": "system@wokelo.ai", "date": "2026-07-21T11:05:15.040079+00:00", "name": "Newsletter Pipeline", "type": "Report", "sub_info": "Newsfeed", "credit_consumed": 10.0 }, { "id": 2670, "email": "rahul.parlani@wokelo.ai", "date": "2026-07-17T14:04:16.175945+00:00", "name": "Arbor Memorial Inc. - Add Company", "type": "API", "sub_info": "Add Company", "credit_consumed": 0.0 } ], "credits_consumed": 0 } ``` **Response Fields** | Field | Type | Description | | - | - | - | | `count` | integer | Total number of log entries across all pages. | | `current_page` | integer | The page number returned in this response. | | `total_pages` | integer | Total number of pages available. | | `data` | array | List of individual credit log entries (see below). | | `credits_consumed` | number | Credits consumed by this logging call itself (typically `0`). | **Log Entry Fields** | Field | Type | Description | | - | - | - | | `id` | integer | Unique identifier for the log entry. | | `email` | string | Email of the user who triggered the activity. May be blank for system-generated entries (e.g. scheduled newsletters). | | `date` | string | Timestamp (ISO 8601) of the activity. | | `name` | string | Name of the report, notebook, or task associated with the activity. | | `type` | string | Category of activity. Observed values include `Report`, `Newsletter`, `API`, and `Assistant`. | | `sub_info` | string | Additional context on the specific action taken (e.g. `Add Company`, `Research Plan Validation`, `Newsfeed`). | | `credit_consumed` | number | Credits consumed by this specific activity. | ```json 200 theme={"system"} { "count": 2604, "current_page": 1, "total_pages": 87, "data": [ { "id": 2663, "email": "tarun@wokelo.ai", "date": "2026-07-16T15:29:37.451531+00:00", "name": "Acquisition Target Companies", "type": "Assistant", "sub_info": "generated via deep_research, final summary layer cost", "credit_consumed": 10.0 } ], "credits_consumed": 0 } ``` # Credits Source: https://docs.wokelo.ai/credits ## How credits are calculated Credits are calculated at a granular level based on individual tasks (e.g., sections, parameters, and number of API calls). Consumption depends on multiple factors, including models used, data pipelines ingested, and processing required. Wokelo’s APIs span real-time enrichment, monitoring, insights generation, and workflow automation. As a result, credit usage varies based on the type and depth of output requested and generated. Full visibility into credit usage is available to enterprise administrators.\ \ *Note: Credits consumed for each API is returned in the API response in the "credits\_consumed" field.* ## Credit construct by API type | **API** | **Type** | **Variable** | **Credit Range** | | :- | :- | :- | :- | | Market Map, Target Screening, Buyer Screening | Discovery | Number of companies returned, fields enriched | \$\$ | | Company and Industry Research | Workflow | Sections selected | \$\$\$ | | Peer Comparison | Workflow | Sections selected | \$\$ | | Earnings Analysis | Workflow | Earnings selected | \$ | | Custom Workflow | Workflow | Custom configuration | Custom | ## Guidelines and Notes * Credits are not charged for any section where no data is returned * Workflow-level credit usage may also vary based on inputs such as files uploaded, custom fields selected, and similar variables * Credit constructs are subject to periodic updates as underlying models, data partnerships, and pricing evolve * For pricing discussions or credit limit adjustments, please contact [**sales@wokelo.ai**](mailto:sales@wokelo.ai) # Custom Workflow Source: https://docs.wokelo.ai/custom-workflow-automation-doc Trigger any of Wokelo's pre-built specialist workflows — IC memos, CIM reviews, deal factsheets, M&A opportunity identification, value chain analysis, market sizing, and more — via API, using the same async submit-poll-download pattern as all Workflow APIs. ## 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](/supporting-apis-doc#report-status) endpoint and retrieve the finished report using the [Download Report](/supporting-apis-doc#download-report) endpoint. **The three-step workflow:** ```text theme={"system"} Step 1: POST /api/workflow_manager/start/ → returns report_id Step 2: GET /api/assets/get_notebook_status/ → poll until status = "Completed" Step 3: POST /api/assets/download_report/ → retrieve JSON / PDF / DOCX / PPT ``` **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:** | 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 | > [!NOTE] > > 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** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "value_creation_e469641", "permalink": "air-canada" }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "workflow": "value_creation_e469641", "permalink": "air-canada" } ) report_id = response.json()["report_id"] print(f"Report submitted. report_id: {report_id}") ``` **Step 1 (alternative) — Submit an industry workflow request** ```python theme={"system"} response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "workflow": "industry_research___custom_a842447", "industry_research_topic": "Electric vehicles" } ) report_id = response.json()["report_id"] ``` **Step 2 — Poll for completion** ```python theme={"system"} import time, requests def wait_for_report(report_id, api_key, poll_interval=20, timeout=900): headers = {"Authorization": f"Bearer {api_key}"} elapsed = 0 while elapsed < timeout: r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=headers, params={"report_id": report_id} ) status = r.json().get("status", "") print(f"[{elapsed}s] Status: {status}") if status == "Completed": return True if status == "Failed": raise Exception(f"Report {report_id} failed") time.sleep(poll_interval) elapsed += poll_interval raise TimeoutError(f"Report {report_id} did not complete within {timeout}s") wait_for_report(report_id, api_key="") ``` **Step 3 — Download the report** ```python theme={"system"} result = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers={"Authorization": "Bearer "}, json={"report_id": report_id, "file_type": "json"} ) report = result.json() print(f"Top-level sections: {list(report.keys())}") ``` *** ## 3. Authentication All requests must include a **Bearer token** in the `Authorization` HTTP header. ```text theme={"system"} Authorization: Bearer ``` 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](mailto:support@wokelo.ai) if you do not yet have API access. > [!WARNING] > > 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** ```text theme={"system"} POST https://api.wokelo.ai/api/workflow_manager/start/ ``` All parameters are passed as JSON in the request body. | 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](/supporting-apis-doc#company-search) 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](/supporting-apis-doc#file-upload). Use this to incorporate CIMs, management presentations, expert call transcripts, or proprietary research. | > [!NOTE] > > 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:** ```bash cURL — company workflow theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "ic_memo_(direct_investments)_02918b9", "permalink": "stripe", "workbook_name": "Stripe IC Memo — June 2026" }' ``` ```bash cURL — industry workflow theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "industry_research___custom_a842447", "industry_research_topic": "Electric vehicles", "workbook_name": "EV Industry Attractiveness" }' ``` ```python Python theme={"system"} import requests HEADERS = { "Authorization": "Bearer ", "Content-Type": "application/json" } # Company workflow — M&A Opportunity Identification response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={ "workflow": "value_creation_e469641", "permalink": "air-canada", "workbook_name": "Air Canada M&A Opportunities" } ) print(response.json()) # {"report_id": 86220} # Industry workflow — Industry Attractiveness response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={ "workflow": "industry_research___custom_a842447", "industry_research_topic": "Electric vehicles", "workbook_name": "EV Industry Attractiveness" } ) print(response.json()) # {"report_id": 86221} ``` *** ## 5. Response ### Submission response The initial POST returns immediately with a single field: ```json theme={"system"} { "report_id": 86220 } ``` | 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 Poll `GET /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 **Recommended navigation pattern:** ```python theme={"system"} report = result.json() # Iterate top-level sections (predictable — named by workflow template) for section_name, section_data in report.items(): print(f"\n=== SECTION: {section_name} ===") # Iterate sub-keys within each section (UUID-suffixed — discover by iteration) for sub_key, sub_data in section_data.items(): print(f" Sub-key: {sub_key}") # Most sub-keys have a "summary" field for the main content summary = None if isinstance(sub_data, dict): summary = sub_data.get("summary") or sub_data.get("quick_snapshot") if summary: content = summary if isinstance(summary, str) else str(summary)[:200] print(f" Content preview: {content[:200]}...") ``` **Common sub-key fields across workflow types:** | 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). | **M\&A Opportunity Identification (`value_creation_e469641`) — example structure:** ```text theme={"system"} report ├── "Investment Prioritization Scorecard" │ └── "Opportunity Prioritization Scorecard" │ ├── source: [...] │ └── summary: markdown table of themes × business value × attractiveness ├── "Step 1: Company Information" │ ├── "CP - Quick snapshot_{uuid}" │ │ ├── quick_snapshot: {...} ← firmographics + product details │ │ └── sources: [...] │ └── "CP - Executive summary_{uuid}" │ ├── source: [...] │ └── summary: markdown narrative ├── "Step 2: Company Intent Identification" │ └── "Company Intent Identification" │ ├── source: [...] │ └── summary: markdown table of intent signals + hypothesis statements └── "Step 3: Opportunity Mapping" └── "Theme Identification" ├── source: [...] └── summary: markdown narrative ``` ### 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. ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "workflow": "value_creation_e469641", "permalink": "air-canada", "workbook_name": "Air Canada M&A Opportunity Identification" }' ``` ```python Python theme={"system"} import requests, time API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} # Submit submit = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={ "workflow": "value_creation_e469641", "permalink": "air-canada", "workbook_name": "Air Canada M&A Opportunity Identification" } ) report_id = submit.json()["report_id"] print(f"Submitted. report_id: {report_id}") # Poll while True: r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=HEADERS, params={"report_id": report_id} ) status = r.json().get("status") print(f"Status: {status}") if status == "Completed": break if status == "Failed": raise Exception("Report failed") time.sleep(20) # Download result = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers=HEADERS, json={"report_id": report_id, "file_type": "json"} ) report = result.json() print(f"Sections: {list(report.keys())}") ``` **Sample submission response:** ```json theme={"system"} { "report_id": 86220 } ``` ### Industry Attractiveness assessment Run an industry-type workflow to assess attractiveness and potential for a sector. ```python theme={"system"} import requests, time API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} submit = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={ "workflow": "industry_research___custom_a842447", "industry_research_topic": "B2B Embedded Finance", "workbook_name": "B2B Embedded Finance — Industry Attractiveness" } ) report_id = submit.json()["report_id"] print(f"Submitted. report_id: {report_id}") ``` ### CIM Review with an uploaded document Upload a CIM file and run the CIM Review workflow to get AI-synthesised deal insights. ```python theme={"system"} import requests API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}"} # Step 1: Upload the CIM with open("target_company_cim.pdf", "rb") as f: upload_r = requests.post( "https://api.wokelo.ai/api/assets/upload/", headers=HEADERS, files={"files": ("target_company_cim.pdf", f, "application/pdf")} ) file_name = upload_r.json()["fileName"] # Step 2: Submit with the uploaded file submit_r = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={**HEADERS, "Content-Type": "application/json"}, json={ "workflow": "martec_cim_review_memo_71a4d4a", "permalink": "target-company-permalink", "custom_files": [{"fileName": file_name}], "workbook_name": "Target Co — CIM Review" } ) report_id = submit_r.json()["report_id"] print(f"CIM Review submitted. report_id: {report_id}") ``` ### Navigating the output JSON Because sub-keys within each section use UUID-suffixed names, navigate by iterating rather than hardcoding paths. ```python theme={"system"} report = result.json() # --- Extract the scorecard summary table --- scorecard_section = report.get("Investment Prioritization Scorecard", {}) for sub_key, sub_data in scorecard_section.items(): summary = sub_data.get("summary", "") if summary: print("=== SCORECARD ===") print(summary[:1000]) # --- Extract company snapshot from Step 1 --- step1 = report.get("Step 1: Company Information", {}) for sub_key, sub_data in step1.items(): if "quick_snapshot" in sub_data: qs = sub_data["quick_snapshot"] name = qs["company_firmographics"]["organization"]["name"] fin = qs["company_firmographics"]["details"].get("financials", {}) rev = fin.get("revenue", {}) print(f"\n=== {name} ===") if rev: print(f"Revenue: ${rev.get('value', 0) / 1e9:.1f}B ({rev.get('period', 'N/A')})") elif "summary" in sub_data: print(f"\n--- {sub_key.split('_')[0]} ---") print(sub_data["summary"][:500]) # --- Extract intent signals from Step 2 --- step2 = report.get("Step 2: Company Intent Identification", {}) for sub_key, sub_data in step2.items(): summary = sub_data.get("summary", "") if summary: print("\n=== INTENT SIGNALS (excerpt) ===") print(summary[:800]) # --- Print all step summaries --- for section_name, section_data in report.items(): print(f"\n{'='*60}") print(f"SECTION: {section_name}") for sub_key, sub_data in section_data.items(): if isinstance(sub_data, dict) and "summary" in sub_data: s = sub_data["summary"] if isinstance(s, str): print(f" [{sub_key[:40]}] {s[:200]}...") ``` ### Batch custom workflows across a portfolio Run M\&A Opportunity Identification or IC Memo workflows across a set of companies concurrently. ```python theme={"system"} import requests, time, concurrent.futures API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} COMPANIES = [ ("air-canada", "value_creation_e469641"), ("delta-airlines", "value_creation_e469641"), ("southwest-airlines", "ic_memo_(direct_investments)_02918b9"), ] def submit_workflow(permalink, workflow_id): r = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={"workflow": workflow_id, "permalink": permalink} ) return permalink, r.json()["report_id"] def poll_until_done(report_id, interval=20, timeout=900): elapsed = 0 while elapsed < timeout: r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=HEADERS, params={"report_id": report_id} ) status = r.json().get("status") if status == "Completed": return True if status == "Failed": return False time.sleep(interval) elapsed += interval return False def fetch_report(report_id): r = requests.post( "https://api.wokelo.ai/api/assets/download_report/", headers=HEADERS, json={"report_id": report_id, "file_type": "json"} ) return r.json() # Submit all concurrently with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool: futures = {pool.submit(submit_workflow, p, w): p for p, w in COMPANIES} jobs = {} for f in concurrent.futures.as_completed(futures): permalink, report_id = f.result() jobs[permalink] = report_id print(f"Submitted: {permalink} → {report_id}") # Poll and collect reports = {} for permalink, report_id in jobs.items(): ok = poll_until_done(report_id) if ok: reports[permalink] = fetch_report(report_id) print(f"Collected: {permalink}") else: print(f"Failed: {permalink}") ``` ### Expert Call Synthesis with a transcript file Upload a call transcript and run Expert Call Synthesis to extract structured takeaways. ```python theme={"system"} import requests API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}"} # Upload the transcript with open("expert_call_transcript.pdf", "rb") as f: upload_r = requests.post( "https://api.wokelo.ai/api/assets/upload/", headers=HEADERS, files={"files": ("expert_call_transcript.pdf", f, "application/pdf")} ) file_name = upload_r.json()["fileName"] # Submit submit_r = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={**HEADERS, "Content-Type": "application/json"}, json={ "workflow": "expert_call_synthesis_f6a6a60", "permalink": "target-company-permalink", "custom_files": [{"fileName": file_name}], "workbook_name": "Expert Call — Supply Chain VP" } ) report_id = submit_r.json()["report_id"] print(f"Synthesis submitted. report_id: {report_id}") ``` *** ## 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](mailto: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](mailto:support@wokelo.ai). | **Handling a `"Failed"` report status:** ```python theme={"system"} status_r = requests.get( "https://api.wokelo.ai/api/assets/get_notebook_status/", headers=HEADERS, params={"report_id": report_id} ) if status_r.json().get("status") == "Failed": print(f"Report {report_id} failed. Resubmitting...") resubmit = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=HEADERS, json={"workflow": "value_creation_e469641", "permalink": "air-canada"} ) print(f"New report_id: {resubmit.json()['report_id']}") ``` **Retry with exponential back-off:** ```python theme={"system"} import time, requests def submit_with_retry(body, api_key, max_retries=3): headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } for attempt in range(max_retries): try: r = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers=headers, json=body, timeout=30 ) if r.status_code == 429: time.sleep(2 ** attempt) continue r.raise_for_status() return r.json()["report_id"] except requests.exceptions.Timeout: if attempt == max_retries - 1: raise time.sleep(1) raise Exception(f"Submission failed after {max_retries} attempts") ``` *** ## 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: ```python theme={"system"} # ❌ Company workflow with no company identifier — will fail {"workflow": "value_creation_e469641"} # ✅ Company workflow with permalink {"workflow": "value_creation_e469641", "permalink": "air-canada"} # ❌ Industry workflow with a permalink instead of topic — will fail {"workflow": "industry_research___custom_a842447", "permalink": "tesla-motors"} # ✅ Industry workflow with a topic {"workflow": "industry_research___custom_a842447", "industry_research_topic": "Electric vehicles"} ``` **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: ```python theme={"system"} # Upload → get fileName → pass in custom_files upload_r = requests.post("https://api.wokelo.ai/api/assets/upload/", ...) file_name = upload_r.json()["fileName"] json_body["custom_files"] = [{"fileName": file_name}] ``` **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: ```python theme={"system"} # ❌ Brittle — assumes a specific UUID in the sub-key name summary = report["Step 1: Company Information"]["CP - Quick snapshot_3b3f08c6-..."]["summary"] # ✅ Resilient — discovers sub-keys by iteration step1 = report.get("Step 1: Company Information", {}) for sub_key, sub_data in step1.items(): if isinstance(sub_data, dict) and "summary" in sub_data: print(sub_data["summary"]) ``` **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: ```python theme={"system"} for wait in [20, 20, 30, 30, 60, 60, 120]: time.sleep(wait) status = get_status(report_id) if status in ("Completed", "Failed"): break ``` **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](mailto:support@wokelo.ai) to confirm which templates are included in your plan before building production automations around them. *** ## 9. Related APIs > **[Company Research](/company-research-doc)** > > The standard async company deep-dive — same endpoint and polling flow, fixed `"company_primer"` workflow producing a consistent five-section report. > **[Industry Research](/industry-research-doc)** > > The standard async industry primer — same endpoint and polling flow, fixed `"industry_primer"` workflow. > **[Peer Comparison](/peer-comparison-doc)** > > Side-by-side benchmarking of 2–5 companies — same endpoint, fixed `"player_comparison"` workflow. > **[Company News Monitoring](/company-news-monitoring-doc)** > > Real-time news feed for any company — synchronous, no polling. Useful for keeping custom workflow outputs current with latest developments. > **[Supporting APIs](/supporting-apis-doc)** > > File Upload, Report Status, and Download Report — all required to run Custom Workflow end-to-end. > **[Company Search](/supporting-apis-doc#company-search)** > > Resolve a company name to its Wokelo permalink — needed before passing `permalink` to any company-type workflow. # Custom Workflows Source: https://docs.wokelo.ai/custom-workflows POST https://api.wokelo.ai/api/workflow_manager/start/ ## Overview Run your pre-configured custom workflows to generate company or industry reports in your specific format. ## Endpoint Details * **Method:** POST * **Endpoint:** `/api/workflow_manager/start/` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request ### Request Parameters #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request #### Body Parameters **workbook\_name** `string` Name with which the workbook will be saved **workflow** `string` *required* Your workflow ID from the dashboard URL (e.g., `comp_research_f312g` from *app.wokelo.ai/dashboard/workflows/comp\_research\_f312g/*) **permalink** `string` *required* Crunchbase permalink of the company. Required for company-based workflows. **website** `string` *required* Website of the company. Required for company-based workflows. **industry\_research\_topic** `string` *required* `For company workflows`: Company's industry (optional—leaves blank to use Wokelo's auto-detected industry) `For industry workflows`: Industry to analyze (required) **custom\_files** `array of objects` Files to include in the report—use `fileName` values from the upload response *Note: Either of company's permalink or website is required for the company-based workflows* ## Response Successful response will include the report\_id of the custom report #### Successful Response Fields **report\_id** `integer` Report id for the initiated custom report ```json 200 theme={"system"} { "report_id": 86220 } ``` # DealCloud Source: https://docs.wokelo.ai/deal-cloud ## Overview Wokelo seamlessly integrates with DealCloud to auto-generate research and enrich your deal pipeline in a secure, compliant way. By bridging due diligence with relationship and deal management, we eliminate manual data entry and embed updated, context-aware insights directly into your Entries—empowering your team to evaluate opportunities faster than before. ## Key Capabilities & Workflows ### **Enterprise-Grade Security** We operate on a restricted access model, connecting only to the specific Pipelines, EntryTypes, and Fields you explicitly authorize. Your sensitive deal data, private notes, and relationship intelligence remain completely isolated from the integration. ### Intelligent Pipeline Triggers Wokelo connects to DealCloud's event system, enabling automated research at critical deal milestones: * **Entry Creation** — Generate instant company profiles when new Companies or Deals are added * **Pipeline Stage Changes** — Trigger due diligence reports when deals advance to DD or IC stages * **Bespoke Workflow Execution** — We execute your custom research workflows and write structured outputs back into DealCloud. ### Seamless Insight Enrichment Wokelo writes insights directly back into DealCloud. We push findings from your custom workflows to Entry fields, deal records, or Activity logs—keeping your data decision-ready at all times. ## Use Cases * **New Entry Added** — When a new company or target is created in DealCloud, Wokelo automatically initiates the appropriate research workflow. There is no need for manual requests; the background analysis starts the moment the record appears. * **Status Change** — As a deal moves through your pipeline stages, Wokelo detects the status change and triggers the specific depth of analysis required for that new phase. * **Insights Enrichment** — Wokelo pushes key findings directly back into your DealCloud fields and grids. ![Image](https://mintcdn.com/wokeloai-7cd44985/DGQO6tiPIb5g8QQq/images/image-16.png?fit=max\&auto=format\&n=DGQO6tiPIb5g8QQq\&q=85\&s=fe3c63bb268f446c4d94116c14d7ae4c) ![Image](https://mintcdn.com/wokeloai-7cd44985/DGQO6tiPIb5g8QQq/images/image-17.png?fit=max\&auto=format\&n=DGQO6tiPIb5g8QQq\&q=85\&s=0cfccd3c025312f018bce9947d30cc8e) ![Image](https://mintcdn.com/wokeloai-7cd44985/DGQO6tiPIb5g8QQq/images/image-18.png?fit=max\&auto=format\&n=DGQO6tiPIb5g8QQq\&q=85\&s=6ac1718ca4e458393b9788df9fac1ec8) ## Get Started Ready to bring automated due diligence into your DealCloud workflow? Click below to get started. [Integrate Deal Cloud →](/mintlify-homepage?contact=true) [Integrate Deal Cloud →](/contact) # Download Report Source: https://docs.wokelo.ai/download-report POST /api/assets/download_report/ Downloads the generated report in the required format. Supported formats: `pdf`, `docx`, and `json`. - For `json` format, the response body contains the structured report data. - For `pdf` and `docx`, the response contains the binary file content. ## Overview Downloads the generated report in the required format such as docx, pdf, and json. The format is passed in the request body. ## Endpoint Details * **Method:** POST * **Endpoint:** `/api/assets/download_report/` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request ### Request Parameter #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request #### Body Parameters **file\_type** `string` *required* Export format. Permitted values: "pdf", "docx", "json" **report\_id** `integer` *required* Id of the report to be exported ## Response Successful response will include download the file in the specified format ```json 200 theme={"system"} { "Executive Summary": { "Executive Summary": { "summary": { "source": [ { "id": 1, "title": "openPR.com L4 Self-driving Vehicle Market Current Status and Future Prospects till 2033", "url": "https://www.openpr.com/news/4132700/l4-self-driving-vehicle-market-current-status-and-future", "publisher": "", "date": "" } ] } } } } ``` # Dropbox Source: https://docs.wokelo.ai/dropbox ## Overview Connect your Dropbox account to Wokelo and seamlessly convert your existing documents into AI-powered research insights. Through a secure OAuth connection, select files directly from Dropbox and feed them into our research agents to generate actionable analysis—no data migration required. ## Integration Capabilities * **Comprehensive file support** — Word, PowerPoint, Excel, PDF, text, CSV. * **Preserves your workflow** — Works with existing folder structures without reorganization * **Enterprise security** — Fully encrypted and SOC 2 Type II compliant ## Use-cases * **Due diligence research** — Analyze CIMs, board decks, and KPI files for comprehensive company assessments * **Custom workflow integration** — Incorporate Dropbox documents into tailored research processes * **Intelligent document querying** — Ask natural language questions like "What is the latest ARR by region?" across your file library * **Report generation** — Create investor briefs, DDQs, and presentation decks directly from selected Dropbox content ## How it works Selecting files from Dropbox is a seamless step while running your workflows on Wokelo * On the file upload step, click on Dropbox's icon * If you’re uploading files for the first time, you might be redirected to a login screen to authenticate your account. ![Image](https://mintcdn.com/wokeloai-7cd44985/fDidDi7K7rWhxEan/images/image-59.png?fit=max\&auto=format\&n=fDidDi7K7rWhxEan\&q=85\&s=c217b08bffbdb2a310bd499f6f6450cf) * This brings up the files you have available in Dropbox. Select the relevant files you want to be included in your research, and click on Choose in the bottom right corner to upload the selected files. ![Image](https://mintcdn.com/wokeloai-7cd44985/dr9AzDK6N773l7iq/images/image-51.png?fit=max\&auto=format\&n=dr9AzDK6N773l7iq\&q=85\&s=709cdb39a5aa505b5ad80880712734c2) * Once uploaded, you would see a list of files that will be used in the workflow. Click Next to trigger the report with the relevant files. ![Image](https://mintcdn.com/wokeloai-7cd44985/dr9AzDK6N773l7iq/images/image-50.png?fit=max\&auto=format\&n=dr9AzDK6N773l7iq\&q=85\&s=b9d0e268cf4506e58633aad85df29295) [Integrate Dropbox →](contact) # Dynamic 365 Source: https://docs.wokelo.ai/dynamic-365 ## Overview Wokelo seamlessly integrates with Microsoft Dynamics 365 to auto-generate research and enrich your pipeline in a secure, compliant way. By bridging due diligence with your existing Sales Hub workflows and the Power Platform, we eliminate manual research and embed updated, context-aware insights directly into your Account and Opportunity records—empowering your team to evaluate opportunities faster than before. ## Key Capabilities & Workflows ### Enterprise-Grade Security We operate on a restricted access model, connecting only to the specific Dataverse tables and columns you explicitly authorize. Your sensitive pipelines, private notes, and contact data remain completely isolated from the integration. ### Automated Research Triggers Instantly launch analysis based on deal activity enabling intelligent automated research workflow triggers: * **Business Process Flow stage change** — Moving an Opportunity through your BPF stages triggers a company research workflow. * **New Account created** — Adding a new Account initiates a company research flow automatically. * **Bespoke Workflow Execution** — We execute your custom research workflows via Power Automate and write structured outputs back into Dynamics 365. ### Seamless Insight Enrichment Wokelo writes insights directly back into your workflow. We can push sections from your custom research to Account or Opportunity columns, the Timeline, or Notes—ensuring data is always decision-ready. ## Use Cases * **New Account added** — When a new company is added to your Dynamics 365 CRM, Wokelo automatically kicks off the right research workflow for that Account. There's no need for your team to manually request, track, or manage research reports—everything starts running in the background as soon as the company appears. * **Stage change** — When an Opportunity moves through your Business Process Flow (for example, from Qualify to Develop), Wokelo detects the change and automatically runs your custom workflow for that stage. This ensures your team always has the right level of insight at the right point in the deal cycle. ![Image](https://mintcdn.com/wokeloai-7cd44985/VRa5y3VmSHCVsVPv/images/image-11.png?fit=max\&auto=format\&n=VRa5y3VmSHCVsVPv\&q=85\&s=6c637c407b23dcdd8acb7f8039aa3c27) ![Image](https://mintcdn.com/wokeloai-7cd44985/GerG9ibLFLH5mxbM/images/image-22.png?fit=max\&auto=format\&n=GerG9ibLFLH5mxbM\&q=85\&s=517b9871ad35f503247327859172d8e3) ![Image](https://mintcdn.com/wokeloai-7cd44985/GerG9ibLFLH5mxbM/images/image-23.png?fit=max\&auto=format\&n=GerG9ibLFLH5mxbM\&q=85\&s=ede4881d187d7bbc1297d405ee99624b) ## Get Started Ready to bring automated due diligence into your Dynamics 365 workflow? Click below to get started. [Integrate Integrate Dynamics 365 →](/contact) # Email Automation Source: https://docs.wokelo.ai/email-automation Wokelo's email integration allows you to create Company and Industry Research reports just by sending an email. ## How it works ### Company Research 1. Send us an email at [research@wokelo.ai](mailto:research@wokelo.ai) with the following details:\ **Subject:** Company Research \ **Email Content:** Company Name, Company Website ![Image](https://mintcdn.com/wokeloai-7cd44985/_xlBAa66nln7CtnL/images/image-28.png?fit=max\&auto=format\&n=_xlBAa66nln7CtnL\&q=85\&s=06456d4407a13aa6838c267a73a78988) 2. Your Company Research report will be initiated for the matched company ![Image](https://mintcdn.com/wokeloai-7cd44985/MY3g4mLP_rdSTHLd/images/image-35.png?fit=max\&auto=format\&n=MY3g4mLP_rdSTHLd\&q=85\&s=907d0b94db948e99aa68e11f2f285d86) 1. If we find multiple companies that match the company name, we’ll request you to select the intended company. ![Image](https://mintcdn.com/wokeloai-7cd44985/MY3g4mLP_rdSTHLd/images/image-36.png?fit=max\&auto=format\&n=MY3g4mLP_rdSTHLd\&q=85\&s=7e34922fa501a2c4fd4d29bee7284fa5) 2. Once you click on the intended company, an email will be auto-generated with the request's details. You can send that email as is and your report will be initiated. ![Image](https://mintcdn.com/wokeloai-7cd44985/MY3g4mLP_rdSTHLd/images/image-38.png?fit=max\&auto=format\&n=MY3g4mLP_rdSTHLd\&q=85\&s=a0bb7fd010afa6852faf11d8018cd06d) ### Industry Research 1. Send us an email at [research@wokelo.ai](mailto:research@wokelo.ai) with the following details: \ **Subject:** Industry Research \ **Email Content:** Industry Name ![Image](https://mintcdn.com/wokeloai-7cd44985/_xlBAa66nln7CtnL/images/image-31.png?fit=max\&auto=format\&n=_xlBAa66nln7CtnL\&q=85\&s=867734002ef161269e4ca1bdb6924cbc) 2. Wokelo will confirm the initiation of the report and share the report pdf once generated. ![Image](https://mintcdn.com/wokeloai-7cd44985/0O6yV850Y_W7YOPl/images/image-34.png?fit=max\&auto=format\&n=0O6yV850Y_W7YOPl\&q=85\&s=c0f8c6fe7f29b4dcc519cbbe06ccb962) Have questions? Reach out to us at [support@wokelo.ai](mailto:support@wokelo.ai). # FAQs Source: https://docs.wokelo.ai/faqs ## Access & Setup > **How do I activate my Wokelo account?** > > Your account is provisioned by your organization admin or the Wokelo team. Once activated, you’ll receive login credentials via email, which can be used to access the platform and generate API tokens. > **Where can I find my API credentials?** > > API credentials (`client_id`, `client_secret`) are available on the **API Credentials** page within the Wokelo platform. These are organization-level credentials and should be securely stored on your backend. > **Can I request a separate API account for my organization?** > > Yes. Wokelo supports organization-level account provisioning, including separate API credentials for different teams or environments (e.g., staging vs production). Reach out to your account team to configure this. ## Usage, Credits & Performance > **How can I track my remaining API credits?** > > Credit usage and remaining balance are available to enterprise admins within the platform. Credits are consumed based on API type, parameters selected, and output complexity. > **How long does it take to generate an output?** > > Latency varies by API type: > > * **Real-time / lightweight APIs (e.g., Monitoring):** seconds > * **Enrichment / Insights APIs:** typically seconds to a few minutes > * **Workflow / deep analysis outputs:** can take around 20-25 minutes depending on sections selected > > All long-running requests return a `request_id` or report ID for asynchronous tracking > **How should I handle latency in production?** > > Many Wokelo APIs are asynchronous and return a `request_id`, especially for deeper analysis and workflow-based outputs. Instead of blocking on a response, you should design your integration to: > > * Submit the request and persist the `request_id` > * Track progress via status endpoints or webhooks > * Fetch results once processing is complete > > Wokelo supports **webhooks** to notify your system when a request is completed, eliminating the need for constant polling. This is recommended for production use cases where you want to trigger downstream workflows (e.g., storing results, notifying users, or chaining analyses) as soon as outputs are ready. > **Can I process requests in bulk?** > > Yes. Several APIs support **multi-entity inputs** (e.g., multiple companies in a single request). For large-scale usage, batching requests and handling them asynchronously is recommended. Our Company Enrichment Instant APIs are mostly used for batch processing and enrichment. ## Data & Coverage > **How recent is the data provided by Wokelo?** > > Wokelo integrates real-time pipelines and continuously refreshed datasets. Most data elements (except company enrichment) are always pulled live. Certain other data elements (\<10%) we partner with providers we have a daily or weekly refresh cycle. > **What should I do if I can’t find a company in search?** > > If a company is not found: All endpoints except company enrichment instant and monitoring support an on-demand addition of companies not available in our ever-growing database. For such cases based on website URL our agents will extract structured information and proceed with analysis asked > > If you face any issues, you can reach out to Wokelo support. ## Product & API Design > **How are Wokelo APIs different from standard LLM APIs?** > > Wokelo APIs are **workflow-oriented, domain-specific, and powered by a large-scale proprietary + public company dataset (20M+ entities)**—not just generic prompt-response interfaces. > > Key differences: > > * **Data + reasoning combined**: Built on top of structured, continuously updated company and industry data—not just model priors > * **Pre-built workflows**: Native support for investment use cases like market mapping, screening, diligence, and research—no need to design prompts or orchestration from scratch > * **Deterministic inputs, structured outputs**: Use filters, parameters, and defined sections instead of free-form prompting; outputs are consistent and machine-readable > * **Multi-step intelligence layer**: Combines enrichment, synthesis, and reasoning into a single API call rather than requiring multiple LLM interactions > * **Production-ready by design**: Handles scale, async execution, and repeatability for enterprise workflows > > Wokelo combines **large-scale structured data with best-in-class agents** to deliver an industry-leading API platform—trusted by marquee financial institutions and enterprises for high-stakes decision-making. > **I have a specific API or workflow requirement—how can I proceed?** > > Wokelo supports both **out-of-the-box APIs** and **custom workflows** tailored to your use case. > > You can: > > * Use existing APIs with configurable parameters and custom fields > * Use custom workflows using the **Custom Workflow API** or notebooks > * Request tailored endpoints, data integrations, or workflow configurations via your account team > > For more complex requirements (e.g., proprietary scoring models, custom datasets, or multi-step pipelines), the Wokelo team can help design and deploy **bespoke solutions aligned to your internal workflows**. > **How are Wokelo APIs different from standard LLM APIs?** > > Wokelo APIs are **workflow-oriented, domain-specific, and powered by a large-scale proprietary + public company dataset (20M+ entities)**—not just generic prompt-response interfaces. > > Key differences: > > * **Data + reasoning combined**: Built on top of structured, continuously updated company and industry data—not just model priors > * **Pre-built workflows**: Native support for investment use cases like market mapping, screening, diligence, and research—no need to design prompts or orchestration from scratch > * **Deterministic inputs, structured outputs**: Use filters, parameters, and defined sections instead of free-form prompting; outputs are consistent and machine-readable > * **Multi-step intelligence layer**: Combines enrichment, synthesis, and reasoning into a single API call rather than requiring multiple LLM interactions > * **Production-ready by design**: Handles scale, async execution, and repeatability for enterprise workflows > > Wokelo combines **large-scale structured data with best-in-class agents** to deliver an industry-leading API platform—trusted by marquee financial institutions and enterprises for high-stakes decision-making. > **I have a specific API or workflow requirement—how can I proceed?** > > Wokelo supports both **out-of-the-box APIs** and **custom workflows** tailored to your use case. > > You can: > > * Use existing APIs with configurable parameters and custom fields > * Build custom workflows using the **Custom Workflow API** or notebooks > * Request tailored endpoints, data integrations, or workflow configurations via your account team > > For more complex requirements (e.g., proprietary scoring models, custom datasets, or multi-step pipelines), the Wokelo team can help design and deploy **bespoke solutions aligned to your internal workflows**. ## Security > **Where is my data stored?** > > Wokelo runs on secure cloud infrastructure with enterprise-grade controls, including encryption at rest and in transit, access isolation, and audit mechanisms. > **Will Wokelo use my data to train its models?** > > No. Customer data is not used to train Wokelo’s internal models. > > If external AI providers are used, they are contractually restricted from retaining or training on customer data. > **What admin controls are available and how can I access them?** > > Enterprise admins have access to: > > * API credential management > * Usage and credit tracking > * User access controls > * Workflow and report visibility > > These controls are available within the Wokelo platform’s admin interface. Access is granted based on role permissions. ## Deployment > **Do you offer VPC or private deployment options?** > > Yes. Wokelo supports enterprise deployments including VPC and private environment setups. Configuration depends on security and compliance requirements—contact your account team for details. # Form Type Filters Source: https://docs.wokelo.ai/form-type-filters Form types used in the form\_type parameter across all Wokelo API endpoints. | **Form Type** | | :- | | 10-12B | | 10-12B/A | | 10-12G | | 10-12G/A | | 10-C | | 10-D | | 10-D/A | | 10-K | | 10-K405 | | 10-K405/A | | 10-K/A | | 10KSB | | 10KSB40 | | 10KSB40/A | | 10KSB/A | | 10-KT | | 10KT405 | | 10-KT/A | | 10-Q | | 10-Q/A | | 10QSB | | 10QSB/A | | 10-QT | | 10-QT/A | | 10SB12B | | 10SB12B/A | | 10SB12G | | 10SB12G/A | | 11-K | | 11-K/A | | 11-KT | | 12G3-2B | | 12G32BR | | 13F-HR | | 13F-HR/A | | 13F-NT | | 13F-NT/A | | 144 | | 144/A | | 15-12B | | 15-12B/A | | 15-12G | | 15-12G/A | | 15-15D | | 15-15D/A | | 15F-12B | | 15F-12B/A | | 15F-12G | | 15F-12G/A | | 15F-15D | | 15F-15D/A | | 18-K | | 18-K/A | | 19B-4E | | 1-A | | 1-A/A | | 1-A POS | | 1-A-W | | 1-A-W/A | | 1-E | | 1-E/A | | 1-K | | 1-K/A | | 1-SA | | 1-SA/A | | 1-U | | 1-U/A | | 1-Z | | 1-Z-W | | 20-F | | 20-F/A | | 20FR12B | | 20FR12B/A | | 20FR12G | | 20FR12G/A | | 24F-2NT | | 24F-2NT/A | | 24F-2TM | | 25 | | 253G1 | | 253G2 | | 253G3 | | 253G4 | | 25/A | | 25-NSE | | 25-NSE/A | | 2-A | | 2-A/A | | 2-E | | 3 | | 305B2 | | 305B2/A | | 34-12H | | 35-APP | | 35-CERT | | 35-CERT/A | | 3/A | | 4 | | 4/A | | 5 | | 5/A | | 40-17F1 | | 40-17F2 | | 40-17F2/A | | 40-17G | | 40-17G/A | | 40-17GCS | | 40-33 | | 40-6B | | 40-6B/A | | 40-6C | | 40-6C/A | | 40-8B25 | | 40-8F-2 | | 40-8F-2/A | | 40-APP | | 40-APP/A | | 40-F | | 40-F/A | | 40FR12B | | 40FR12B/A | | 40FR12G | | 40FR12G/A | | 424A | | 424B1 | | 424B2 | | 424B3 | | 424B4 | | 424B5 | | 424B7 | | 424B8 | | 424I | | 425 | | 485APOS | | 485BPOS | | 485BXT | | 486APOS | | 486BPOS | | 486BXT | | 497 | | 497AD | | 497H2 | | 497J | | 497K | | 6B NTC | | 6B ORDR | | 6-K | | 6-K/A | | 8-A12B | | 8-A12B/A | | 8A12BT | | 8A12BT/A | | 8-A12G | | 8-A12G/A | | 8F-2 NTC | | 8F-2 ORDR | | 8-K | | 8-K12B | | 8-K12B/A | | 8-K12G3 | | 8-K12G3/A | | 8-K15D5 | | 8-K15D5/A | | 8-K/A | | ABS-15G | | ABS-15G/A | | ADN-MTL | | ANNLRPT | | APP NTC | | APP ORDR | | APP WD | | APP WD/A | | APP WDG | | ARS | | ARS/A | | AW | | AW WD | | C | | C/A | | C-AR | | C-AR/A | | CB | | CB/A | | CERT | | CERTAMX | | CERTARCA | | CERTNAS | | CERTNYS | | CERTPAC | | CERTPBS | | CORRESP | | CT ORDER | | C-TR | | C-U | | C-W | | D | | D/A | | DEF 14A | | DEF 14C | | DEFA14A | | DEFA14C | | DEFC14A | | DEFC14C | | DEFM14A | | DEFM14C | | DEFN14A | | DEFR14A | | DEFR14C | | DEFS14A | | DEFS14C | | DEL AM | | DFAN14A | | DFRN14A | | DOS | | DOS/A | | DOSLTR | | DRS | | DRS/A | | DRSLTR | | EFFECT | | F-1 | | F-10 | | F-10/A | | F-10EF | | F-10POS | | F-1/A | | F-1MEF | | F-2 | | F-2/A | | F-3 | | F-3/A | | F-3ASR | | F-3D | | F-3DPOS | | F-3MEF | | F-4 | | F-4/A | | F-4MEF | | F-4 POS | | F-6 | | F-6/A | | F-6EF | | F-6 POS | | F-7 | | F-8 | | F-80 | | F-80/A | | F-80POS | | F-8/A | | F-8 POS | | F-9 | | F-9/A | | F-9 POS | | F-N | | F-N/A | | FWP | | F-X | | F-X/A | | IRANNOTICE | | MA-I | | MA-I/A | | N-14 | | N-14 8C | | N-14 8C/A | | N-14/A | | N-14MEF | | N-1A | | N-1A/A | | N-2 | | N-23C-1 | | N-23C-1/A | | N-23C-2 | | N-23C-2/A | | N-23C3A | | N-23C3A/A | | N-23C3B | | N-23C3C | | N-23C3C/A | | N-2/A | | N-2ASR | | N-2MEF | | N-2 POSASR | | N-30B-2 | | N-30D | | N-30D/A | | N-5 | | N-54A | | N-54A/A | | N-54C | | N-5/A | | N-6F | | N-6F/A | | N-8A | | N-8A/A | | N-8B-2 | | N-8B-2/A | | N-8F | | N-8F/A | | N-8F NTC | | N-8F ORDR | | N-CEN | | N-CEN/A | | N-CSR | | N-CSR/A | | N-CSRS | | N-CSRS/A | | NO ACT | | NPORT-EX | | NPORT-EX/A | | NPORT-P | | NPORT-P/A | | N-PX | | N-PX/A | | N-Q | | N-Q/A | | NSAR-A | | NSAR-A/A | | NSAR-AT | | NSAR-B | | NSAR-B/A | | NSAR-BT | | NSAR-BT/A | | NSAR-U | | NSAR-U/A | | NT 10-K | | NT 10-K/A | | NT 10-Q | | NT 10-Q/A | | NT 11-K | | NT 11-K/A | | NT 15D2 | | NT 20-F | | NT 20-F/A | | NTFNCEN | | NTFNCSR | | NTFNSAR | | NTN 10K | | NTN 10Q | | NTN 20F | | NT N-CEN | | NT-NCEN | | NT-NCSR | | NT-NCSR/A | | NT NPORT-EX | | NT NPORT-P | | NT-NSAR | | NT-NSAR/A | | POS462B | | POS462C | | POS 8C | | POS AM | | POS AMC | | POS AMI | | POSASR | | POS EX | | PRE13E3 | | PRE13E3/A | | PRE 14A | | PRE 14C | | PREA14A | | PREC14A | | PREC14C | | PREM14A | | PREM14C | | PREN14A | | PRER14A | | PRER14C | | PRES14A | | PRES14C | | PRRN14A | | PX14A6G | | PX14A6N | | QUALIF | | REGDEX | | REGDEX/A | | REVOKED | | RW | | RW WD | | S-1 | | S-11 | | S-11/A | | S-11MEF | | S-1/A | | S-1MEF | | S-2 | | S-2/A | | S-2MEF | | S-3 | | S-3/A | | S-3ASR | | S-3D | | S-3DPOS | | S-3MEF | | S-4 | | S-4/A | | S-4EF | | S-4EF/A | | S-4MEF | | S-4 POS | | S-6 | | S-6/A | | S-6EL24 | | S-6EL24/A | | S-8 | | S-8 POS | | S-B | | SB-1 | | SB-1/A | | SB-2 | | SB-2/A | | SB-2MEF | | S-B/A | | SBSE-A | | SBSE-A/A | | SBSE-C | | SC 13D | | SC 13D/A | | SC 13E1 | | SC 13E3 | | SC 13E3/A | | SC 13E4 | | SC 13E4/A | | SC13E4F | | SC13E4F/A | | SC 13G | | SC 13G/A | | SC 14D1 | | SC 14D1/A | | SC14D1F | | SC14D1F/A | | SC 14D9 | | SC 14D9/A | | SC14D9C | | SC 14F1 | | SC 14F1/A | | SC 14N | | SC 14N/A | | SCHEDULE 13D | | SCHEDULE 13D/A | | SCHEDULE 13G | | SCHEDULE 13G/A | | SC TO-C | | SC TO-I | | SC TO-I/A | | SC TO-T | | SC TO-T/A | | SD | | SD/A | | SE | | SEC ACTION | | SEC STAFF ACTION | | SEC STAFF LETTER | | SF-1 | | SF-1/A | | SP 15D2 | | SPDSCL | | SUPPL | | T-3 | | T-3/A | | TH | | U-1 | | U-1/A | | U-12-IA | | U-12-IB | | U-13E-1 | | U-3A-2 | | U-3A-2/A | | U-57 | | U-57/A | | U5A | | U5B | | U5S | | U5S/A | | U-6B-2 | | U-6B-2/A | | U-7D/A | | UNDER | | UPLOAD | # Fundraising Activity Source: https://docs.wokelo.ai/fundraise POST https://api.wokelo.ai/api/workflow_manager/start/ ## Overview The Fundraising Activity API surfaces the funding activity that has taken place in a given industry domain. You can refine the output by transaction date, funding round type, transaction amount, company type, geography, and employee count. Fundraising Activity runs as a workflow. Set `workflow` to `fundraisers_workflow` in the request body to start one. The request returns a `report_id`, which you then use to track completion and export the results. ## Endpoint Details * Method: POST * Endpoint: `/api/workflow_manager/start/` ## Authentication Requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request ### Body Parameters **topic** `string` *required* Industry topic to surface funding activity for (e.g. `"Neo databases"`) **workflow** `string` *required* The workflow to run. Must be `"fundraisers_workflow"` for Fundraising Activity. **workbook\_name** `string` *required* Name of the workbook that will hold the generated report (e.g. `"Neo databases"`) **advanced\_settings** `object` Filter parameters object. All filters live inside `advanced_settings`. Include the object in every request, and send empty values (`[]`) for any filter you do not want to apply. #### Funding filters **transaction\_date** `object` Filter by the date of the funding transaction. Dates use the `YYYY-MM-DD` format. **from** `string` Earliest transaction date (inclusive), e.g. `"2023-10-28"` **to** `string` Latest transaction date (inclusive), e.g. `"2026-10-29"` **transaction\_funding\_round\_type** `string[]` Filter by funding round type (e.g. `"Seed"`, `"Series A"`). Pass an empty array to include all round types. **transaction\_amount** `object` Filter by funding transaction amount (in million USD). **from** `number` Minimum transaction amount, e.g. `5` **to** `number` Maximum transaction amount, e.g. `100` **transaction\_amount\_include\_blanks** `boolean` When `true`, funding transactions with no disclosed amount are included in the results alongside transactions that match the `transaction_amount` range. #### Company filters **company\_type** `string` Type of company to include. Accepted values: `"private"`, `"public"`, `"all"` **geography** `string[]` Geographic scope. Pass `["Worldwide"]` for no geographic restriction, or a list of ISO country codes (e.g. `["USA", "GBR"]`). **employee\_count** `string[]` Filter by employee headcount range. Pass an empty array to include all headcounts. Supported array values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+` ```json Basic request theme={"system"} { "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "transaction_funding_round_type": [], "employee_count": [], "transaction_amount_include_blanks": true, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" } } } ``` ```json Request with filters theme={"system"} { "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "private", "geography": ["USA", "GBR"], "transaction_funding_round_type": ["Seed", "Series A"], "employee_count": ["11-50", "51-100"], "transaction_amount": { "from": 5, "to": 100 }, "transaction_amount_include_blanks": false, "transaction_date": { "from": "2024-01-01", "to": "2026-10-29" } } } ``` ```javascript JavaScript - Fetch theme={"system"} const myHeaders = new Headers(); myHeaders.append("Content-Type", "application/json"); myHeaders.append("Authorization", "your token"); const raw = JSON.stringify({ "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "transaction_funding_round_type": [], "employee_count": [], "transaction_amount_include_blanks": true, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" } } }); const requestOptions = { method: "POST", headers: myHeaders, body: raw, redirect: "follow" }; fetch("https://api.wokelo.ai/api/workflow_manager/start/", requestOptions) .then((response) => response.text()) .then((result) => console.log(result)) .catch((error) => console.error(error)); ``` ```python Python theme={"system"} import requests headers = {"Content-Type": "application/json", "Authorization": "Bearer YOUR_TOKEN"} payload = { "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "transaction_funding_round_type": [], "employee_count": [], "transaction_amount_include_blanks": True, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" } } } response = requests.post("https://api.wokelo.ai/api/workflow_manager/start/", headers=headers, json=payload) print(response.json()) ``` ```bash cURL theme={"system"} curl --request POST \ --url https://api.wokelo.ai/api/workflow_manager/start/ \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "transaction_funding_round_type": [], "employee_count": [], "transaction_amount_include_blanks": true, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" } } }' ``` ```go Go theme={"system"} package main import ( "bytes" "encoding/json" "fmt" "io" "net/http" ) func main() { advSettings := map[string]interface{}{ "company_type": "all", "geography": []string{"Worldwide"}, "transaction_funding_round_type": []string{}, "employee_count": []string{}, "transaction_amount_include_blanks": true, "transaction_date": map[string]string{ "from": "2023-10-28", "to": "2026-10-29", }, } payload := map[string]interface{}{ "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": advSettings, } body, _ := json.Marshal(payload) req, _ := http.NewRequest("POST", "https://api.wokelo.ai/api/workflow_manager/start/", bytes.NewBuffer(body)) req.Header.Set("Authorization", "Bearer YOUR_TOKEN") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() respBody, _ := io.ReadAll(resp.Body) fmt.Println(string(respBody)) } ``` ```java Java theme={"system"} import java.net.URI; import java.net.http.*; public class FundraiseWorkflow { public static void main(String[] args) throws Exception { String body = "{\"topic\":\"Neo databases\",\"workflow\":\"fundraisers_workflow\",\"workbook_name\":\"Neo databases\",\"advanced_settings\":{\"company_type\":\"all\",\"geography\":[\"Worldwide\"],\"transaction_funding_round_type\":[],\"employee_count\":[],\"transaction_amount_include_blanks\":true,\"transaction_date\":{\"from\":\"2023-10-28\",\"to\":\"2026-10-29\"}}}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.wokelo.ai/api/workflow_manager/start/")) .header("Authorization", "Bearer YOUR_TOKEN") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponse response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ``` ### Response A successful response returns a `report_id` that identifies the Fundraising Activity report. #### Successful Response Fields **report\_id** `integer` Unique identifier for the report created by this request. Use it to track completion and to download the results (see below). ```json 200 theme={"system"} { "report_id": 123345 } ``` ## Tracking Completion and Exporting Results Fundraising Activity generation is asynchronous. After you receive a `report_id`: 1. Use `/api/assets/get_notebook_status/` to track completion of the report. 2. Once the report is complete, use `/api/assets/download_report/` to export the results. # Fundraise Activity Source: https://docs.wokelo.ai/fundraise-doc Surface funding rounds in a given industry domain with amounts, stages, investors, company profiles and news context. ## 1. Overview The Fundraise Activity API surfaces the funding rounds that have taken place in a given industry domain. Each record shows which company raised, at what stage, from which investors, on what date, what the company does, and relevant news coverage. This is an **asynchronous API**. Starting the workflow returns a `report_id`, which you use to track completion and export the results. See [How Async APIs work](/how-async-apis-work). Each record includes round metadata (date, stage, amount, lead and other investors), company firmographics and business profile, and curated news. A company appears once per funding event, so you can reconstruct its full financing history by grouping on `Permalink`. **Common use cases:** * **Market intelligence**: track which investors are most active in a sector * **Startup scouting**: surface early-stage companies in niche categories * **Portfolio monitoring**: catch new funding events in categories you track *** ## 2. Quick Start **Step 1: Start the workflow** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "transaction_funding_round_type": [], "employee_count": [], "transaction_amount_include_blanks": true, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" } } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "all", "geography": ["Worldwide"], "transaction_funding_round_type": [], "employee_count": [], "transaction_amount_include_blanks": True, "transaction_date": { "from": "2023-10-28", "to": "2026-10-29" } } } ) print(response.json()["report_id"]) ``` The response contains a `report_id`. **Step 2: Track completion** Use `/api/assets/get_notebook_status/` with the `report_id` to check whether the report has completed. **Step 3: Export results** Once the report is complete, use `/api/assets/download_report/` with the `report_id` to export the results. *** ## 3. Authentication Include a Bearer token in the `Authorization` header of every request. ```text theme={"system"} Authorization: Bearer ``` Obtain a token from the `/auth/token/` endpoint using the client id and client secret under **Account Details → API Credentials** in the Wokelo dashboard. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access. > [!WARNING] > > Never expose your token in client-side code or public repositories. *** ## 4. Request Reference **Endpoint** ```text theme={"system"} POST https://api.wokelo.ai/api/workflow_manager/start/ ``` The request body is JSON. Include `advanced_settings` in every request and send empty values (`[]`) for filters you do not want to apply. Dates use the `YYYY-MM-DD` format. | Parameter | Type | Required | Description | | - | - | - | - | | `topic` | string | **Required** | Industry topic to surface funding activity for (e.g. `"Neo databases"`). | | `workflow` | string | **Required** | Must be `"fundraisers_workflow"`. | | `workbook_name` | string | **Required** | Name of the workbook that holds the generated report. | | `advanced_settings` | object | Optional | Filter parameters. All filters below live inside this object. | | `advanced_settings.transaction_date` | object | Optional | Object with `from` and/or `to` (`YYYY-MM-DD`, inclusive). | | `advanced_settings.transaction_funding_round_type` | string\[] | Optional | Funding round types (e.g. `"Seed"`, `"Series A"`). Empty array includes all. | | `advanced_settings.transaction_amount` | object | Optional | Object with `from` and/or `to`, in million USD. | | `advanced_settings.transaction_amount_include_blanks` | boolean | Optional | When `true`, rounds with no disclosed amount are included. | | `advanced_settings.company_type` | string | Optional | `"private"`, `"public"` or `"all"`. | | `advanced_settings.geography` | string\[] | Optional | `["Worldwide"]` for no restriction, or ISO country codes (e.g. `["USA", "GBR"]`). | | `advanced_settings.employee_count` | string\[] | Optional | Headcount bands. Empty array includes all. Values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+`. | *** ## 5. Response ### Workflow start response ```json theme={"system"} { "report_id": 117253 } ``` | Field | Type | Description | | - | - | - | | `report_id` | integer | Unique identifier of the report. Use it to track completion and export results. | ### Report output fields | Field | Description | | - | - | | `Permalink` | Stable company identifier. The same value repeats across a company's rounds. | | `Funding Date` | `YYYY-MM-DD`. | | `Funding Stage` | Round classification, e.g. `Pre-seed`, `Seed`, `Series A` to `Series J`, `Angel round`, `Convertible note`, `Grant`, `Debt-Funded`, `Private equity round`, `Corporate-Funded`, `Non-Equity Assistance`, `Undisclosed`. | | `Funding Amount ($M)` | Round size. Null when undisclosed. | | `Lead Investor(s)`, `Other Investor(s)` | Arrays of investor names. Null when none were identified. | | `Name`, `Website` | Company that raised and its primary domain. | | `HQ City`, `HQ Country`, `HQ Continent`, `Founded` | Headquarters location and founding year. | | `Employees (Crunchbase)`, `Employees (LinkedIn)` | Headcount band and numeric headcount. | | `Product Category`, `Core Offering`, `Product Catalog` | Product category, AI-generated description and key products. | | `News` | Unstructured text of news summaries, each followed by a source URL. Null when no coverage was indexed. | *** ## 6. Examples ### Filtered funding rounds Seed and Series A rounds of \$5M to \$100M for private companies in the USA and UK between 2024 and 2026. ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "private", "geography": ["USA", "GBR"], "transaction_funding_round_type": ["Seed", "Series A"], "employee_count": ["11-50", "51-100"], "transaction_amount": { "from": 5, "to": 100 }, "transaction_amount_include_blanks": false, "transaction_date": { "from": "2024-01-01", "to": "2026-10-29" } } }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "topic": "Neo databases", "workflow": "fundraisers_workflow", "workbook_name": "Neo databases", "advanced_settings": { "company_type": "private", "geography": ["USA", "GBR"], "transaction_funding_round_type": ["Seed", "Series A"], "employee_count": ["11-50", "51-100"], "transaction_amount": { "from": 5, "to": 100 }, "transaction_amount_include_blanks": False, "transaction_date": { "from": "2024-01-01", "to": "2026-10-29" } } } ) print(response.json()["report_id"]) ``` *** # Get Report Status Source: https://docs.wokelo.ai/get-report-status GET /api/assets/get_notebook_status/ Retrieves the current status of a previously triggered report using its unique ID. Poll this endpoint until the status is `Completed`, `Exported`, or `No Data Found`. Possible status values: - `Completed` - `Processing` - `Queued` - `Delayed` - `Exported` - `No Data Found` ## Overview Retrieves the current status of a previously triggered report using its unique ID. ## Endpoint Details * **Method:** GET * **Endpoint:** `api/assets/get_notebook_status/` ## Authentication requirements * Include a valid JWT token in your request header * If you don't have a token yet, you can get one from the `/auth/token/` endpoint first. ## Request ### Request Parameters #### Header Parameters **Authorization** `string` *required* JWT token obtained from the Authentication request ### URL Parameters **report\_id** `integer` *required* The id returned in response to the start report request ## Response Successful response will return the status along with report\_id and title. List of status codes: 1. Completed 2. Processing 3. Queued 4. Delayed 5. Exported 6. No Data Found ```json 200 theme={"system"} { "report_id": 98564, "status": "Delayed", "title": "One Signal" } ``` # Getting started Source: https://docs.wokelo.ai/getting-started Access your API credentials from the [API Credentials page](https://app.wokelo.ai/dashboard/profile/api-credentials). ## Authentication All API requests must be authenticated using a JWT token. Follow the steps below to generate your token: * Use the authentication endpoint: `https://api.wokelo.ai/auth/token/` * Use the Client ID and Client Secret from the API Credentials page, along with your email and password. Set the grant type to `"password"`. * The response contains your JWT token. Pass it in the `Authorization` header of every request as `Bearer `. ```bash cURL wrap theme={"system"} curl --location 'https://api.wokelo.ai/auth/token/' \ --form 'username="sam@abconsulting.com"' \ --form 'password="password"' \ --form 'grant_type="password"' \ --form 'client_id="YOUR_CLIENT_ID"' \ --form 'client_secret="YOUR_CLIENT_SECRET"' ``` ```python Python expandable wrap theme={"system"} import requests url = "https://api.wokelo.ai/auth/token/" payload = { 'username': 'sam@abconsulting.com', 'password': 'password', 'grant_type': 'password', 'client_id': 'YOUR_CLIENT_ID', 'client_secret': 'YOUR_CLIENT_SECRET' } files = [] headers = {} response = requests.request("POST", url, headers=headers, data=payload, files=files) print(response.text) ``` ## Make your first API call Let's try the Market Map API. Wokelo APIs are asynchronous: you start a workflow, track its status, and then download the report. See [How Async APIs work](/how-async-apis-work) for details. ### Step 1: Start the workflow ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "topic": "warehouse automation", "workflow": "agentic_mm", "workbook_name": "warehouse automation", "advanced_settings": { "detailed_query": "warehouse automation", "companies": [], "company_type": "all", "geography": ["Worldwide"], "employee_count": [], "funding_stage": [], "total_funding_include_blanks": true } }' ``` ```python Python wrap theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/workflow_manager/start/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "topic": "warehouse automation", "workflow": "agentic_mm", "workbook_name": "warehouse automation", "advanced_settings": { "detailed_query": "warehouse automation", "companies": [], "company_type": "all", "geography": ["Worldwide"], "employee_count": [], "funding_stage": [], "total_funding_include_blanks": True } } ) report_id = response.json()["report_id"] print("Report started:", report_id) ``` A successful request returns a `report_id`: ```json theme={"system"} { "report_id": 117253 } ``` ### Step 2: Check the report status Use the `report_id` to track completion with `/api/assets/get_notebook_status/`. ```bash theme={"system"} curl --request GET \ --url 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=117253' \ --header 'Authorization: Bearer ' ``` ```json theme={"system"} { "report_id": 117253, "status": "Completed", "title": "warehouse automation" } ``` ### Step 3: Download the report Once the status is `Completed`, export the results with `/api/assets/download_report/`. Set `file_type` to `pdf`, `docx` or `json`. ```bash theme={"system"} curl --request POST \ --url https://api.wokelo.ai/api/assets/download_report/ \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --output report.pdf \ --data '{ "report_id": 117253, "file_type": "pdf" }' ``` ## Next steps * Review the [Market Map API reference](/market-map-doc) for all available filters. * Not sure which API to use? See [Choosing the right API](/choosing-the-right-api). # Glossary Source: https://docs.wokelo.ai/glossary List of key terms, concepts, and abbreviations used across the API documentation. | **Term** | **Definition** | | :- | :- | | Access Token | JWT bearer token used to authenticate API requests | | Async API | An API that returns a tracking ID; results retrieved via polling | | Custom Field | An AI-computed data point added to enrichment via a user-defined prompt | | DXA | Document eXchange unit of measurement (1440 DXA = 1 inch) used in report formatting | | Enrichment | The process of augmenting a company record with additional data | | Firmographics | Basic company attributes: name, HQ, industry, year founded, etc. | | JWT | JSON Web Token — the authentication mechanism used by Wokelo APIs | | Notebook | Wokelo's internal container for a workflow-generated report | | Permalink | A unique, URL-safe slug identifying a company (e.g., "tesla-motors") | | Refresh Token | A long-lived token used to obtain new access tokens without re-authentication | | Report ID | An integer identifier for tracking workflow report generation | | Request ID | A UUID identifier for tracking async API requests | | Section | A named data module in an enrichment or insights request | | Sync API | An API that returns results directly in the HTTP response | | Workflow | A pre-defined or custom research template that generates exportable reports | # Google Drive Source: https://docs.wokelo.ai/google-drive ## Overview Connect your Google Drive to Wokelo and seamlessly convert your existing documents into AI-powered research insights. Through a secure authentication connection, select files directly from Google Drive and feed them into our research agents to generate actionable analysis—no data migration required. ## Integration Capabilities * **Comprehensive file support** — Word, PowerPoint, Excel, PDF, text, CSV. * **Preserves your workflow** — Works with existing folder structures without reorganization * **Enterprise security** — Fully encrypted and SOC 2 Type II compliant ## Use-cases * **Due diligence research** — Analyze CIMs, board decks, and KPI files for comprehensive company assessments * **Custom workflow integration** — Incorporate Google Drive documents into tailored research processes * **Intelligent document querying** — Ask natural language questions like "What is the latest ARR by region?" across your file library * **Report generation** — Create investor briefs, DDQs, and presentation decks directly from selected Google Drive content ## How it works Selecting files from Google Drive is a seamless step while running your workflows on Wokelo * On the file upload step, click on Google Drive’s icon ![Image](https://mintcdn.com/wokeloai-7cd44985/MY3g4mLP_rdSTHLd/images/image-46.png?fit=max\&auto=format\&n=MY3g4mLP_rdSTHLd\&q=85\&s=250d3fb478f1be1f59c5657e8659f841) * If you’re uploading files for the first time, you might be redirected to a login screen to authenticate your account. ![Image](https://mintcdn.com/wokeloai-7cd44985/MY3g4mLP_rdSTHLd/images/image-47.png?fit=max\&auto=format\&n=MY3g4mLP_rdSTHLd\&q=85\&s=67956428dd7000303905c580443f80df) * This brings up the files you have available in Google Drive. Select the relevant files you want to be included in your research, and click on Choose in the bottom right corner to upload the selected files. ![Image](https://mintcdn.com/wokeloai-7cd44985/VRa5y3VmSHCVsVPv/images/image-8.png?fit=max\&auto=format\&n=VRa5y3VmSHCVsVPv\&q=85\&s=1c82b058173d02f70563d04aa151ae80) * Once uploaded, you would see a list of files that will be used in the workflow. Click Next to trigger the report with the relevant files. ![Image](https://mintcdn.com/wokeloai-7cd44985/U70KDdDmmTnzCWV4/images/image-5.png?fit=max\&auto=format\&n=U70KDdDmmTnzCWV4\&q=85\&s=193302c47c485b559196756545fc3e30) [Integrate Google Drive →](/contact) # Home Source: https://docs.wokelo.ai/home Build with Wokelo # Build With Wokelo Explore API reference, integration guides, and updates to seamlessly build with Wokelo Request API Access ![Wokelo API Hero](https://mintcdn.com/wokeloai-7cd44985/-hc5eJ-TVS_Awa75/images/hero-image.png?fit=max\&auto=format\&n=-hc5eJ-TVS_Awa75\&q=85\&s=dcdcbbde4c90bcef5e63e672c040125a) ## See it work

 Questions? Contact Sales

[For LLMs. llms.txt](/llms.txt)


# How Async APIs work
Source: https://docs.wokelo.ai/how-async-apis-work



## Overview

Wokelo APIs in the **Discovery** and **Workflow Automation** categories operate asynchronously. These operations involve deep AI research, large-scale data enrichment and multi-source synthesis, so they can take several minutes to complete. Rather than keeping your HTTP connection open for that entire duration, Wokelo uses a **Submit, Check Status, Download** pattern.

Every async API returns a `report_id` as soon as the request is accepted. This ID is your handle for everything that follows. Your integration stays non-blocking: submit a job, move on, and download the results when they are ready.

## Why Asynchronous?

Wokelo produces intelligence at investment-grade quality, resolving entities, deduplicating signals across sources and running structured AI workflows. This depth takes time, and a synchronous API would need to hold a connection open for the full run.

The async pattern lets you:

* **Decouple submission from retrieval**: start a job and handle the result whenever it is ready
* **Handle long-running tasks reliably**: no timeout failures on deep research jobs
* **Run multiple requests in parallel**: submit many jobs at once and track each by its `report_id`
* **Integrate cleanly into pipelines**: queue results, trigger downstream workflows, or store outputs on completion

## The Three-Step Flow

```text theme={"system"}
1. SUBMIT   POST /api/workflow_manager/start/       →  returns report_id
2. STATUS   GET  /api/assets/get_notebook_status/   →  returns status
3. DOWNLOAD POST /api/assets/download_report/       →  returns the report
```

### Step 1: Submit a Request

Call the relevant API endpoint with your parameters. The API returns immediately with a `report_id`.

**Example: starting a Market Map workflow**

```bash theme={"system"}
curl --request POST \
  --url https://api.wokelo.ai/api/workflow_manager/start/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "warehouse automation",
    "workflow": "agentic_mm",
    "workbook_name": "warehouse automation",
    "advanced_settings": {
      "detailed_query": "warehouse automation",
      "companies": [],
      "company_type": "all",
      "geography": ["Worldwide"],
      "employee_count": [],
      "funding_stage": [],
      "total_funding_include_blanks": true
    }
  }'
```

**Response:**

```json theme={"system"}
{
  "report_id": 117253
}
```

> **Save the `report_id`.** You need it in Steps 2 and 3.

### Step 2: Check Report Status

After submitting, periodically call the **Get Report Status** endpoint with your `report_id`.

```text theme={"system"}
GET /api/assets/get_notebook_status/?report_id={your_report_id}
```

**Example:**

```bash theme={"system"}
curl --request GET \
  --url 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=117253' \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

**Response:**

```json theme={"system"}
{
  "report_id": 117253,
  "status": "Processing",
  "title": "warehouse automation"
}
```

#### Status values

| Status | Meaning |
| - | - |
| `Queued` | The report has been received and is waiting to be processed. |
| `Processing` | The report is actively being generated. |
| `Delayed` | The report is taking longer than expected. |
| `Completed` | Generation finished successfully. The report is ready to download. |
| `Exported` | The report has been exported. |
| `No Data Found` | No data was found for the request. |

Poll with a gradually increasing interval rather than a tight loop. Polling more often does not speed up results.

#### Polling code examples

```python theme={"system"}
# Python: polling with exponential backoff
import requests
import time

headers = {"Authorization": "Bearer YOUR_TOKEN"}
report_id = 117253
interval = 10  # seconds

while True:
    response = requests.get(
        "https://api.wokelo.ai/api/assets/get_notebook_status/",
        headers=headers,
        params={"report_id": report_id}
    )
    status = response.json()["status"]
    print(f"Status: {status}")

    if status in ("Completed", "Exported"):
        break
    if status == "No Data Found":
        raise Exception(f"No data found for report {report_id}")

    time.sleep(interval)
    interval = min(interval * 1.5, 60)  # cap at 60 seconds
```

```javascript theme={"system"}
// JavaScript: async polling loop
async function pollForCompletion(reportId, token) {
  const url = `https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=${reportId}`;
  const headers = { Authorization: `Bearer ${token}` };
  let interval = 10000; // start at 10s

  while (true) {
    const res = await fetch(url, { headers });
    const data = await res.json();
    console.log("Status:", data.status);

    if (data.status === "Completed" || data.status === "Exported") return data;
    if (data.status === "No Data Found") throw new Error("No data found");

    await new Promise((resolve) => setTimeout(resolve, interval));
    interval = Math.min(interval * 1.5, 60000); // cap at 60s
  }
}
```

```go theme={"system"}
// Go: polling loop with sleep
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

func pollStatus(reportID, token string) {
    interval := 10 * time.Second
    for {
        req, _ := http.NewRequest("GET",
            "https://api.wokelo.ai/api/assets/get_notebook_status/?report_id="+reportID, nil)
        req.Header.Set("Authorization", "Bearer "+token)
        resp, _ := http.DefaultClient.Do(req)
        body, _ := io.ReadAll(resp.Body)
        resp.Body.Close()

        var result map[string]interface{}
        json.Unmarshal(body, &result)
        status := result["status"].(string)
        fmt.Println("Status:", status)

        if status == "Completed" || status == "Exported" || status == "No Data Found" {
            fmt.Println(string(body))
            return
        }
        time.Sleep(interval)
        if interval < 60*time.Second {
            interval = time.Duration(float64(interval) * 1.5)
        }
    }
}
```

### Step 3: Download the Report

Once the status is `Completed`, export the report with the **Download Report** endpoint. Pass the `report_id` and the export format in the request body.

```text theme={"system"}
POST /api/assets/download_report/
```

| Body parameter | Type | Required | Description |
| - | - | - | - |
| `report_id` | integer | Yes | Id of the report to export. |
| `file_type` | string | Yes | Export format. One of `"pdf"`, `"docx"`, `"json"`. |

**Example:**

```bash theme={"system"}
curl --request POST \
  --url https://api.wokelo.ai/api/assets/download_report/ \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --output report.pdf \
  --data '{
    "report_id": 117253,
    "file_type": "pdf"
  }'
```

The response is the report file in the requested format.

### Complete End-to-End Example

The following Python example shows the full Submit, Status, Download cycle for a Market Map request:

```python theme={"system"}
import requests
import time

BASE_URL = "https://api.wokelo.ai"
HEADERS = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

# STEP 1: Submit
submit = requests.post(
    f"{BASE_URL}/api/workflow_manager/start/",
    headers=HEADERS,
    json={
        "topic": "warehouse automation",
        "workflow": "agentic_mm",
        "workbook_name": "warehouse automation",
        "advanced_settings": {
            "detailed_query": "warehouse automation",
            "companies": [],
            "company_type": "all",
            "geography": ["Worldwide"],
            "employee_count": [],
            "funding_stage": [],
            "total_funding_include_blanks": True
        }
    }
)
report_id = submit.json()["report_id"]
print(f"Submitted. report_id: {report_id}")

# STEP 2: Check status
interval = 15
while True:
    status = requests.get(
        f"{BASE_URL}/api/assets/get_notebook_status/",
        headers=HEADERS,
        params={"report_id": report_id}
    ).json()["status"]
    print(f"Status: {status}")

    if status in ("Completed", "Exported"):
        break
    if status == "No Data Found":
        raise Exception("No data found.")

    time.sleep(interval)
    interval = min(interval * 1.5, 60)

# STEP 3: Download
download = requests.post(
    f"{BASE_URL}/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": report_id, "file_type": "pdf"}
)
with open("report.pdf", "wb") as f:
    f.write(download.content)
print("Report saved to report.pdf")
```


# Industry Names
Source: https://docs.wokelo.ai/industry-names



Accepted values for` industry` field in the Industry News Monitoring API

| Sr. No | Industry Name |
| - | - |
| 1 | Transportation & Logistics |
| 2 | Travel & Hospitality |
| 3 | Energy, Utilities & Environment |
| 4 | Home & Personal Services |
| 5 | Consumer Products & Retail |
| 6 | Agriculture & Food Production |
| 7 | Healthcare & Life Sciences |
| 8 | Hardware, Technology & Telecom |
| 9 | Business & Public Services |
| 10 | Financial & Insurance |
| 11 | Media, Entertainment & Sports |
| 12 | Industrials, Manufacturing & Construction |
| 13 | Education |


# Industry Research
Source: https://docs.wokelo.ai/industry-research

POST https://api.wokelo.ai/api/workflow_manager/start/

## Overview

Starts generating an Industry Research report for your specified industry.

## Endpoint Details

* **Method:** POST
* **Endpoint:** `api/workflow_manager/start/`

## Authentication requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

### Request Parameters

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

#### Body Parameters

**industry** `string` *required*

Industry on which the report will be created

**workflow** `string` *required*

`industry_primer`

**custom\_files** `array of objects`

Files to include in the report. Use fileName values from the file upload response

## Response

Success response will include the report\_id of the Industry Research report

#### Successful Response Fields

**report\_id** `integer`

Report id of the Industry Research

```json 200 theme={"system"}
{
    "report_id": 123345
}
```


# Industry Research
Source: https://docs.wokelo.ai/industry-research-doc

Generate a comprehensive, source-cited sector intelligence report — covering market overview, executive summary, key insights, trends and innovations, and select transaction activity — as a structured JSON, PDF, DOCX, or PPT deliverable.

## 1. Overview

The Industry Research API generates an end-to-end sector intelligence report on any industry or market, covering market sizing, growth drivers, competitive dynamics, innovation trends, and recent transaction activity. 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](/supporting-apis-doc#report-status) endpoint and retrieve the finished report using the [Download Report](/supporting-apis-doc#download-report) endpoint.

**The three-step workflow:**

```text theme={"system"}
Step 1: POST /api/workflow_manager/start/         → returns report_id
Step 2: GET  /api/assets/get_notebook_status/     → poll until status = "Completed"
Step 3: POST /api/assets/download_report/         → retrieve JSON / PDF / DOCX / PPT
```

The completed report is structured into five major sections, each returned as a named key in the JSON output:

* **Executive Summary** — multi-paragraph narrative covering market size, growth drivers, regional dynamics, technology trends, supply chain, and regulatory landscape; fully source-cited with 20–30+ references
* **Key Insights** — 8–10 analyst-style insight cards, each with a headline metric, supporting data paragraph, and multi-point commentary with citations
* **Overview** — structured description of the industry — definition, key offerings, market segments, and core problems the sector solves
* **Trends and Innovations** — detailed synthesis of technological, operational, and strategic trends reshaping the industry, with named company examples and quantified data points
* **Select Transactions** — fundraising activity data for companies in the space, including per-deal records with investor details, funding stage, and amounts; quarterly deal-count and total-funding charts; and a ranked list of key investors

**Common use cases:**

* **Thesis development for new sectors** — generate a sourced, structured primer on any industry before committing diligence resources to it
* **LP and IC briefing decks** — export as PPT or PDF for sector updates, investment committee presentations, or fund strategy reviews
* **Market entry and expansion research** — understand market size, regional dynamics, and competitive structure for any industry in minutes
* **Deal sourcing context** — use the Select Transactions section to identify active fundraising companies and leading investors in a sector
* **Competitive intelligence** — track innovation trends and strategic partnerships across a sector to identify white spaces and disruption vectors
* **Custom report augmentation** — supply `custom_files` to layer proprietary internal research or market data on top of Wokelo's synthesis

> [!NOTE]
>
> 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](/how-async-apis-work) for a full explanation of the polling lifecycle.

***

## 2. Quick Start

**Step 1 — Submit the report request**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "industry_primer",
    "industry": "Warehouse Automation"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "industry_primer",
        "industry": "Warehouse Automation"
    }
)
report_id = response.json()["report_id"]
print(f"Report submitted. report_id: {report_id}")
```

**Step 2 — Poll for completion**

```python theme={"system"}
import time, requests

def wait_for_report(report_id, api_key, poll_interval=15, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=headers,
            params={"report_id": report_id}
        )
        status = r.json().get("status", "")
        print(f"[{elapsed}s] Status: {status}")
        if status == "Completed":
            return True
        if status == "Failed":
            raise Exception(f"Report {report_id} failed")
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise TimeoutError(f"Report {report_id} did not complete within {timeout}s")

wait_for_report(report_id, api_key="")
```

**Step 3 — Download the report**

```python theme={"system"}
# Fetch as JSON for programmatic processing
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")

# Or download as a formatted document
ppt_result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "ppt"}
)
with open("industry_research.pptx", "wb") as f:
    f.write(ppt_result.content)
```

***

## 3. Authentication

All requests must include a **Bearer token** in the `Authorization` HTTP header.

```text theme={"system"}
Authorization: Bearer 
```

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](mailto:support@wokelo.ai) if you do not yet have API access.

> [!WARNING]
>
> 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**

```text theme={"system"}
POST https://api.wokelo.ai/api/workflow_manager/start/
```

All parameters are passed as JSON in the request body.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflow` | string | **Required** | Must always be `"industry_primer"`. This fixed value tells Wokelo's workflow engine to run the Industry Research report. Do not confuse with `"company_primer"` (Company Research) or `"peer_comparison"` (Peer Comparison). |
| `industry` | string | **Required** | Free-text description of the industry or sector to research. Specificity drives report quality — see Best Practices for guidance on phrasing. Examples: `"Warehouse Automation"`, `"Electronics Manufacturing Services"`, `"GLP-1 Obesity Drug Market"`, `"Offshore Wind Energy"`. |
| `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](/supporting-apis-doc#file-upload). Use this to incorporate proprietary market research, analyst reports, or internal sector notes. |

> [!NOTE]
>
> Unlike Company Research, Industry Research has no `permalink`, `website`, or `workbook_name` parameters. The `industry` string is the only identifier and the primary driver of report scope and quality.

**Full request example:**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "industry_primer",
    "industry": "Electronics Manufacturing Services"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "industry_primer",
        "industry": "Electronics Manufacturing Services"
    }
)
print(response.json())   # {"report_id": 123345}
```

***

## 5. Response

### Submission response

The initial POST returns immediately with a single field:

```json theme={"system"}
{
  "report_id": 123345
}
```

| Field | Type | Description |
| - | - | - |
| `report_id` | integer | Unique identifier for this report job. Use it with the Report Status and Download Report endpoints to track and retrieve the completed report. Store this value immediately — it is the only handle to your report. |

### Report status response

Poll `GET /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

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 Industry Research are:

**Executive Summary**

Contains two sub-keys:

* `Executive Summary` → `summary` object with a `source` array of citation objects (`id`, `title`, `url`, `publisher`, `date`) and a `summary` field containing a full markdown-formatted multi-section narrative (Overview, Market Dynamics and Growth Drivers, Regional Market Leadership, Technological Innovation, Supply Chain, Regulatory Environment)
* `Key Insights` → `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

**Overview**

Contains an `industry_overview_details` object with a `source` array and a `summary` field covering: industry definition, how it operates, key offerings (as named and described categories), market segments, and problems being solved.

**Trends and Innovations**

Contains a `trend_and_innovations` object with a `source` array and a `summary` field — a long-form markdown narrative organised by innovation themes (e.g. Advanced Materials, Cybersecurity, Printed Electronics, AI Automation, Predictive Maintenance, Sustainability, Adaptive Manufacturing, Strategic Partnerships).

**Select Transactions**

Contains two sub-keys:

* `Fundraising activities` → `fundraising` object with:
  * `fundraising` array — individual deal records (see below)
  * `key_investors_in_this_space` → `key_investors_in_this_space` array — ranked investor records with `organization` (name, logo, url, permalink), `no_of_investments`, and `key_investments` (array of strings)
  * `sources` array — data attribution (typically Crunchbase)
  * `charts` object — three chart data structures (see below)

**Fundraising deal record fields:**

| Field | Type | Description |
| - | - | - |
| `organization` | object | Company that raised. Contains `name`, `url` (Wokelo dashboard link), `logo`, and `permalink`. |
| `funding` | integer | Raw USD amount raised (e.g. `30000000` for \$30M). Always a numeric integer — never an empty string. |
| `funding_type` | string | Round type. Examples: `"Series A"`, `"Series B"`, `"Seed"`, `"Debt-Funded"`, `"Non-Equity Assistance"`, `"Corporate-Funded"`, `"Private Equity"`. |
| `date` | string | Close date in `DD-Mon-YYYY` format (e.g. `"23-Dec-2025"`). |
| `product_category` | string | Short label for the company's product or service area. |
| `lead_investors` | object\[] | Array of lead investor objects, each with an `organization` sub-object (`name`, `url`, `logo`, `permalink`). May be absent when lead was not publicly disclosed. |
| `investors` | object\[] | Array of non-lead investor objects, same structure as `lead_investors`. May be absent. |

**Chart data structures:**

The `charts` object contains three keys, each with a `title`, `data` array, `source` attribution string, and `url` (pre-rendered chart image):

* `fundraising_line_chart` — quarterly deal count time series. Each data point: `{quarter: "Q3 '24", deals: 13}`
* `fundraising_stage_chart` — quarterly deal count broken out by stage (Seed Stage, Early Stage, Late Stage, Private Equity, Others). Each data point: `{quarter: "Q3 '24", stage: "Early Stage", deals: 3}`
* `fundraising_quarter_wise_chart` — quarterly total funding raised. Each data point uses a two-field value structure: `{quarter: "Q2 '24", funding: {value: 5.4, multiplier: 1000000000}}` — multiply `value × multiplier` to get the raw USD amount

> [!NOTE]
>
> The `fundraising_quarter_wise_chart` uses a `{value, multiplier}` pattern rather than raw integers to keep chart data readable. Always multiply `value × multiplier` before presenting amounts: `5.4 × 1,000,000,000 = $5.4B`. The `multiplier` is typically `1000000` (millions) or `1000000000` (billions), but always check rather than assuming.

### Download format options

| `file_type` | Description |
| - | - |
| `"json"` | Fully structured JSON — all sections, fields, and source citations. Best for programmatic processing, pipeline ingestion, or downstream analysis. |
| `"pdf"` | Formatted PDF report. Best for sharing with stakeholders who need a readable, printable document. |
| `"docx"` | Editable Word document. Best for teams that customise or annotate reports before distribution. |
| `"ppt"` | PowerPoint presentation with section slides. Best for IC presentations, LP updates, and conference briefings. |

***

## 6. Examples

### Basic industry research

Submit, poll, and download JSON — the standard three-step pattern.

```bash cURL theme={"system"}
# Step 1: Submit
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{"workflow": "industry_primer", "industry": "Electronics Manufacturing Services"}'

# Step 2: Poll (replace 123345 with your report_id)
curl --location 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=123345' \
  --header 'Authorization: Bearer '

# Step 3: Download
curl --location 'https://api.wokelo.ai/api/assets/download_report/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{"report_id": 123345, "file_type": "json"}'
```

```python Python theme={"system"}
import requests, time

API_KEY = ""
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Step 1: Submit
submit = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers=HEADERS,
    json={"workflow": "industry_primer", "industry": "Electronics Manufacturing Services"}
)
report_id = submit.json()["report_id"]
print(f"Submitted. report_id: {report_id}")

# Step 2: Poll
while True:
    status_r = requests.get(
        "https://api.wokelo.ai/api/assets/get_notebook_status/",
        headers=HEADERS,
        params={"report_id": report_id}
    )
    status = status_r.json().get("status")
    print(f"Status: {status}")
    if status == "Completed":
        break
    if status == "Failed":
        raise Exception("Report failed")
    time.sleep(15)

# Step 3: Download
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")
```

**Sample submission response:**

```json theme={"system"}
{
  "report_id": 123345
}
```

### Extracting key sections from the JSON report

Work with individual sections for targeted downstream processing.

```python theme={"system"}
# Assume report is already downloaded as a dict
report = result.json()

# --- Executive Summary narrative ---
exec_summary = report["Executive Summary"]["Executive Summary"]["summary"]["summary"]
print("EXECUTIVE SUMMARY (first 500 chars):")
print(exec_summary[:500])
print()

# --- Key Insights headlines ---
insights = report["Executive Summary"]["Key Insights"]["key_insights"]
print(f"KEY INSIGHTS ({len(insights)} total):")
for i, card in enumerate(insights, 1):
    print(f"  {i}. {card['insight']['title']}")
    print(f"     {card['insight']['paragraph'][:120]}...")
print()

# --- Industry overview summary ---
overview = report["Overview"]["Overview"]["industry_overview_details"]["summary"]
print("OVERVIEW (first 400 chars):")
print(overview[:400])
print()

# --- Trends and innovations ---
trends = report["Trends and innovations"]["Key trends and innovations"]["trend_and_innovations"]["summary"]
print(f"TRENDS SECTION LENGTH: {len(trends.split())} words")
print()

# --- Top fundraising deals (by size) ---
deals = report["Select transactions"]["Fundraising activities"]["fundraising"]["fundraising"]
sorted_deals = sorted(deals, key=lambda x: x.get("funding", 0), reverse=True)
print("TOP FUNDRAISING DEALS:")
for deal in sorted_deals[:5]:
    amount_m = deal["funding"] / 1_000_000
    lead = deal.get("lead_investors", [{}])[0].get("organization", {}).get("name", "undisclosed")
    print(f"  ${amount_m:.0f}M  {deal['organization']['name']}  ({deal['funding_type']})  Lead: {lead}")
```

### Parsing fundraising chart data

The quarterly funding chart uses a `{value, multiplier}` two-field pattern. Parse it correctly before presenting amounts.

```python theme={"system"}
charts = report["Select transactions"]["Fundraising activities"]["fundraising"]["fundraising"]["charts"]

# Deal count over time
print("Quarterly Deal Count:")
for pt in charts["fundraising_line_chart"]["data"]:
    print(f"  {pt['quarter']}: {pt['deals']} deals")

# Total funding over time (value × multiplier = USD)
print("\nQuarterly Total Funding:")
for pt in charts["fundraising_quarter_wise_chart"]["data"]:
    f = pt["funding"]
    usd = f["value"] * f["multiplier"]
    if usd >= 1e9:
        label = f"${usd / 1e9:.1f}B"
    else:
        label = f"${usd / 1e6:.0f}M"
    print(f"  {pt['quarter']}: {label}")

# Stage breakdown
print("\nDeals by Stage (most recent quarter):")
stage_data = charts["fundraising_stage_chart"]["data"]
latest_q = stage_data[-1]["quarter"]
latest = [pt for pt in stage_data if pt["quarter"] == latest_q]
for pt in latest:
    print(f"  {pt['stage']}: {pt['deals']} deals")
```

### Identifying top investors in a sector

Use the key investors sub-section to find the most active investors for deal sourcing or LP targeting.

```python theme={"system"}
investors = (
    report["Select transactions"]
    ["Fundraising activities"]
    ["key_investors_in_this_space"]
    ["key_investors_in_this_space"]
)

print(f"Top investors in {industry} ({len(investors)} total):\n")
for inv in investors[:10]:
    org  = inv["organization"]["name"]
    n    = inv["no_of_investments"]
    keys = ", ".join(inv.get("key_investments", []))
    print(f"  {org}  ({n} investments)")
    if keys:
        print(f"    Notable: {keys}")
```

### Batch research across a portfolio of sectors

Submit Industry Research for multiple sectors concurrently, then collect all reports.

```python theme={"system"}
import requests, time, concurrent.futures

API_KEY  = ""
HEADERS  = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

SECTORS = [
    "Warehouse Automation",
    "GLP-1 Obesity Drug Market",
    "Offshore Wind Energy",
    "Electronics Manufacturing Services",
    "Generative AI Infrastructure"
]

def submit_research(industry):
    r = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={"workflow": "industry_primer", "industry": industry}
    )
    return industry, r.json()["report_id"]

def poll_until_done(report_id, interval=20, timeout=900):
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=HEADERS,
            params={"report_id": report_id}
        )
        status = r.json().get("status")
        if status == "Completed":
            return True
        if status == "Failed":
            return False
        time.sleep(interval)
        elapsed += interval
    return False

def fetch_report(report_id):
    r = requests.post(
        "https://api.wokelo.ai/api/assets/download_report/",
        headers=HEADERS,
        json={"report_id": report_id, "file_type": "json"}
    )
    return r.json()

# Submit all concurrently
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool:
    futures = {pool.submit(submit_research, s): s for s in SECTORS}
    jobs = {}
    for future in concurrent.futures.as_completed(futures):
        sector, report_id = future.result()
        jobs[sector] = report_id
        print(f"Submitted: {sector} → report_id {report_id}")

# Poll and collect
reports = {}
for sector, report_id in jobs.items():
    ok = poll_until_done(report_id)
    if ok:
        reports[sector] = fetch_report(report_id)
        print(f"Collected: {sector}")
    else:
        print(f"Failed or timed out: {sector}")

print(f"\nCollected {len(reports)} / {len(SECTORS)} reports")
```

### Research with a custom file

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

```python theme={"system"}
import requests

API_KEY = ""
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Step 1: Upload the file
with open("internal_sector_brief.pdf", "rb") as f:
    upload_r = requests.post(
        "https://api.wokelo.ai/api/assets/upload/",
        headers=HEADERS,
        files={"files": ("internal_sector_brief.pdf", f, "application/pdf")}
    )
file_name = upload_r.json()["fileName"]

# Step 2: Submit report referencing the uploaded file
submit_r = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "workflow":     "industry_primer",
        "industry":     "Carbon Capture and Storage",
        "custom_files": [{"fileName": file_name}]
    }
)
report_id = submit_r.json()["report_id"]
print(f"Report with custom file submitted. report_id: {report_id}")
```

### Exporting as PPT for an IC presentation

```python theme={"system"}
import requests

HEADERS = {"Authorization": "Bearer "}

ppt_r = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": 123345, "file_type": "ppt"}
)

with open("ems_industry_research.pptx", "wb") as f:
    f.write(ppt_r.content)

print("Saved ems_industry_research.pptx")
```

***

## 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`, missing `industry`, or unrecognised `workflow` string. Check the `detail` field. Ensure `workflow` is exactly `"industry_primer"`. |
| `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 endpoint. Contact [support@wokelo.ai](mailto: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](mailto:support@wokelo.ai). |

**Handling a `"Failed"` report status:**

```python theme={"system"}
status_r = requests.get(
    "https://api.wokelo.ai/api/assets/get_notebook_status/",
    headers=HEADERS,
    params={"report_id": report_id}
)
if status_r.json().get("status") == "Failed":
    print(f"Report {report_id} failed. Resubmitting...")
    resubmit = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={"workflow": "industry_primer", "industry": "Warehouse Automation"}
    )
    new_id = resubmit.json()["report_id"]
    print(f"New report_id: {new_id}")
```

**Retry with exponential back-off on submission:**

```python theme={"system"}
import time, requests

def submit_with_retry(body, api_key, max_retries=3):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    for attempt in range(max_retries):
        try:
            r = requests.post(
                "https://api.wokelo.ai/api/workflow_manager/start/",
                headers=headers,
                json=body,
                timeout=30
            )
            if r.status_code == 429:
                time.sleep(2 ** attempt)
                continue
            r.raise_for_status()
            return r.json()["report_id"]
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
    raise Exception(f"Submission failed after {max_retries} attempts")
```

***

## 8. Best Practices

**Be specific and descriptive in the `industry` string — this is the single highest-impact parameter**

The `industry` field is a free-text string, and the specificity of what you write directly determines how focused and useful the report is. Vague inputs like `"technology"` or `"manufacturing"` produce broad, shallow reports. Specific, descriptive inputs produce deep, actionable sector coverage:

```python theme={"system"}
# ❌ Too broad — produces a generic, high-level report
body["industry"] = "Manufacturing"
body["industry"] = "Healthcare"
body["industry"] = "Finance"

# ✅ Specific — produces a focused, high-signal report
body["industry"] = "Electronics Manufacturing Services (EMS)"
body["industry"] = "GLP-1 Obesity Drug Market"
body["industry"] = "Offshore Wind Farm Development"
body["industry"] = "Carbon Capture and Storage Technology"
body["industry"] = "AI-Powered Revenue Cycle Management in Healthcare"
```

**`workflow` must always be `"industry_primer"` — not `"company_primer"`**

The `/api/workflow_manager/start/` endpoint is shared across all Workflow APIs. The `workflow` parameter is what distinguishes Industry Research from Company Research, Peer Comparison, and Custom Workflow. For Industry Research, it must be exactly `"industry_primer"`. Omitting it, misspelling it, or using `"company_primer"` returns a `400` error or generates the wrong report type.

**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 recover past `report_id` values. Store it to a database, log, or job queue entry as soon as the submission response is received:

```python theme={"system"}
report_id = response.json()["report_id"]
# ✅ Persist immediately before any further processing
save_to_db({"sector": industry, "report_id": report_id, "submitted_at": datetime.now()})
```

**Use 15–20 second polling intervals — not tight loops**

Industry Research reports typically complete in 2–5 minutes. Polling more frequently than every 15 seconds wastes rate limit budget without meaningfully reducing wait time. Use a progressive back-off for batch workloads:

```python theme={"system"}
for wait in [15, 15, 30, 30, 60, 60, 120]:
    time.sleep(wait)
    status = get_status(report_id)
    if status in ("Completed", "Failed"):
        break
```

**Parse the `{value, multiplier}` chart pattern defensively**

The quarterly funding chart uses a two-field encoding (`value` × `multiplier`) rather than raw integers. Always compute the actual amount rather than presenting `value` directly — a label of `"5.4"` instead of `"$5.4B"` will confuse stakeholders:

```python theme={"system"}
# ❌ Wrong — presents raw value without multiplier
amount = pt["funding"]["value"]                              # "5.4"

# ✅ Correct — applies the multiplier
amount_usd = pt["funding"]["value"] * pt["funding"]["multiplier"]  # 5400000000.0
```

**Check for absent `lead_investors` / `investors` before accessing them**

Both fields are optional in fundraising deal records — they are omitted entirely (not set to `[]`) when investor information was not publicly disclosed. Always use `.get()` with a default:

```python theme={"system"}
# ❌ KeyError risk when field is absent
lead_name = deal["lead_investors"][0]["organization"]["name"]

# ✅ Safe
leads = deal.get("lead_investors", [])
lead_name = leads[0]["organization"]["name"] if leads else "Undisclosed"
```

**Use `custom_files` to incorporate proprietary research**

The `custom_files` parameter causes Wokelo to synthesise your uploaded documents alongside its web research, producing a report that bridges your internal knowledge with current market data. This is particularly valuable for sectors where you already hold proprietary market maps, prior diligence, or analyst reports. Upload files via the [File Upload API](/supporting-apis-doc#file-upload) first, then pass the returned `fileName` values in the array.

**Use `"json"` for pipelines; `"ppt"` or `"pdf"` for human deliverables**

The JSON output contains all structured data, citation arrays, and chart data. Use it for any programmatic downstream work. The formatted outputs strip much of the metadata but are better suited for IC decks, LP updates, and conference briefings. A single `report_id` supports all four formats — you can download both JSON and PPT for the same report without resubmitting.

**Understand the difference from Industry News Monitoring**

Industry Research and Industry News Monitoring both accept a free-text topic and both cover a sector — but they are fundamentally different in output and use case. Industry News Monitoring returns a paginated list of real-time news articles (synchronous, no report generation). Industry Research returns a synthesised, structured intelligence report with market sizing, trend analysis, and transaction data (asynchronous, minutes to generate). Use Industry News Monitoring for ongoing real-time tracking; use Industry Research for periodic deep-dive primers and one-time sector coverage.

***

## 9. Related APIs

> **[Company Research](/company-research-doc)**
>
> The company-level equivalent — generates a sourced intelligence report on any specific company using the same async workflow pattern.

> **[Peer Comparison](/peer-comparison-doc)**
>
> Generate a structured side-by-side comparison of two or more companies across key dimensions in a single report.

> **[Industry Deep Intelligence](/industry-deep-intelligence-doc)**
>
> Synchronous alternative for structured industry intelligence — returns results directly without the report polling step.

> **[Industry News Monitoring](/industry-news-monitoring-doc)**
>
> Real-time news articles for any industry topic — synchronous, paginated, no polling required. Complements Industry Research for ongoing monitoring.

> **[Newsfeed](/newsfeed-doc)**
>
> Structured multi-industry news feed filtered by sentiment, geography, and event category — ideal for recurring monitoring pipelines.

> **[Supporting APIs](/supporting-apis-doc)**
>
> Report Status, Download Report, and File Upload — all used alongside Industry Research in the async workflow.

## 1. Overview

The Industry Research API generates an end-to-end sector intelligence report on any industry or market, covering market sizing, growth drivers, competitive dynamics, innovation trends, and recent transaction activity. 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](/supporting-apis-doc#report-status) endpoint and retrieve the finished report using the [Download Report](/supporting-apis-doc#download-report) endpoint.

**The three-step workflow:**

```text theme={"system"}
Step 1: POST /api/workflow_manager/start/         → returns report_id
Step 2: GET  /api/assets/get_notebook_status/     → poll until status = "Completed"
Step 3: POST /api/assets/download_report/         → retrieve JSON / PDF / DOCX / PPT
```

The completed report is structured into five major sections, each returned as a named key in the JSON output:

* **Executive Summary** — multi-paragraph narrative covering market size, growth drivers, regional dynamics, technology trends, supply chain, and regulatory landscape; fully source-cited with 20–30+ references
* **Key Insights** — 8–10 analyst-style insight cards, each with a headline metric, supporting data paragraph, and multi-point commentary with citations
* **Overview** — structured description of the industry — definition, key offerings, market segments, and core problems the sector solves
* **Trends and Innovations** — detailed synthesis of technological, operational, and strategic trends reshaping the industry, with named company examples and quantified data points
* **Select Transactions** — fundraising activity data for companies in the space, including per-deal records with investor details, funding stage, and amounts; quarterly deal-count and total-funding charts; and a ranked list of key investors

**Common use cases:**

* **Thesis development for new sectors** — generate a sourced, structured primer on any industry before committing diligence resources to it
* **LP and IC briefing decks** — export as PPT or PDF for sector updates, investment committee presentations, or fund strategy reviews
* **Market entry and expansion research** — understand market size, regional dynamics, and competitive structure for any industry in minutes
* **Deal sourcing context** — use the Select Transactions section to identify active fundraising companies and leading investors in a sector
* **Competitive intelligence** — track innovation trends and strategic partnerships across a sector to identify white spaces and disruption vectors
* **Custom report augmentation** — supply `custom_files` to layer proprietary internal research or market data on top of Wokelo's synthesis

> [!NOTE]
>
> 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](/how-async-apis-work) for a full explanation of the polling lifecycle.

***

## 2. Quick Start

**Step 1 — Submit the report request**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "industry_primer",
    "industry": "Warehouse Automation"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "industry_primer",
        "industry": "Warehouse Automation"
    }
)
report_id = response.json()["report_id"]
print(f"Report submitted. report_id: {report_id}")
```

**Step 2 — Poll for completion**

```python theme={"system"}
import time, requests

def wait_for_report(report_id, api_key, poll_interval=15, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=headers,
            params={"report_id": report_id}
        )
        status = r.json().get("status", "")
        print(f"[{elapsed}s] Status: {status}")
        if status == "Completed":
            return True
        if status == "Failed":
            raise Exception(f"Report {report_id} failed")
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise TimeoutError(f"Report {report_id} did not complete within {timeout}s")

wait_for_report(report_id, api_key="")
```

**Step 3 — Download the report**

```python theme={"system"}
# Fetch as JSON for programmatic processing
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")

# Or download as a formatted document
ppt_result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "ppt"}
)
with open("industry_research.pptx", "wb") as f:
    f.write(ppt_result.content)
```

***

## 3. Authentication

All requests must include a **Bearer token** in the `Authorization` HTTP header.

```text theme={"system"}
Authorization: Bearer 
```

API tokens are issued from your Wokelo account. Navigate to **Settings → API Keys** in the Wokelo dashboard to generate or rotate a key. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access.

> [!WARNING]
>
> 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**

```text theme={"system"}
POST https://api.wokelo.ai/api/workflow_manager/start/
```

All parameters are passed as JSON in the request body.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflow` | string | **Required** | Must always be `"industry_primer"`. This fixed value tells Wokelo's workflow engine to run the Industry Research report. Do not confuse with `"company_primer"` (Company Research) or `"peer_comparison"` (Peer Comparison). |
| `industry` | string | **Required** | Free-text description of the industry or sector to research. Specificity drives report quality — see Best Practices for guidance on phrasing. Examples: `"Warehouse Automation"`, `"Electronics Manufacturing Services"`, `"GLP-1 Obesity Drug Market"`, `"Offshore Wind Energy"`. |
| `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](/supporting-apis-doc#file-upload). Use this to incorporate proprietary market research, analyst reports, or internal sector notes. |

> [!NOTE]
>
> Unlike Company Research, Industry Research has no `permalink`, `website`, or `workbook_name` parameters. The `industry` string is the only identifier and the primary driver of report scope and quality.

**Full request example:**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "industry_primer",
    "industry": "Electronics Manufacturing Services"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "industry_primer",
        "industry": "Electronics Manufacturing Services"
    }
)
print(response.json())   # {"report_id": 123345}
```

***

## 5. Response

### Submission response

The initial POST returns immediately with a single field:

```json theme={"system"}
{
  "report_id": 123345
}
```

| Field | Type | Description |
| - | - | - |
| `report_id` | integer | Unique identifier for this report job. Use it with the Report Status and Download Report endpoints to track and retrieve the completed report. Store this value immediately — it is the only handle to your report. |

### Report status response

Poll `GET /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

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 Industry Research are:

**Executive Summary**

Contains two sub-keys:

* `Executive Summary` → `summary` object with a `source` array of citation objects (`id`, `title`, `url`, `publisher`, `date`) and a `summary` field containing a full markdown-formatted multi-section narrative (Overview, Market Dynamics and Growth Drivers, Regional Market Leadership, Technological Innovation, Supply Chain, Regulatory Environment)
* `Key Insights` → `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

**Overview**

Contains an `industry_overview_details` object with a `source` array and a `summary` field covering: industry definition, how it operates, key offerings (as named and described categories), market segments, and problems being solved.

**Trends and Innovations**

Contains a `trend_and_innovations` object with a `source` array and a `summary` field — a long-form markdown narrative organised by innovation themes (e.g. Advanced Materials, Cybersecurity, Printed Electronics, AI Automation, Predictive Maintenance, Sustainability, Adaptive Manufacturing, Strategic Partnerships).

**Select Transactions**

Contains two sub-keys:

* `Fundraising activities` → `fundraising` object with:
  * `fundraising` array — individual deal records (see below)
  * `key_investors_in_this_space` → `key_investors_in_this_space` array — ranked investor records with `organization` (name, logo, url, permalink), `no_of_investments`, and `key_investments` (array of strings)
  * `sources` array — data attribution (typically Crunchbase)
  * `charts` object — three chart data structures (see below)

**Fundraising deal record fields:**

| Field | Type | Description |
| - | - | - |
| `organization` | object | Company that raised. Contains `name`, `url` (Wokelo dashboard link), `logo`, and `permalink`. |
| `funding` | integer | Raw USD amount raised (e.g. `30000000` for \$30M). Always a numeric integer — never an empty string. |
| `funding_type` | string | Round type. Examples: `"Series A"`, `"Series B"`, `"Seed"`, `"Debt-Funded"`, `"Non-Equity Assistance"`, `"Corporate-Funded"`, `"Private Equity"`. |
| `date` | string | Close date in `DD-Mon-YYYY` format (e.g. `"23-Dec-2025"`). |
| `product_category` | string | Short label for the company's product or service area. |
| `lead_investors` | object\[] | Array of lead investor objects, each with an `organization` sub-object (`name`, `url`, `logo`, `permalink`). May be absent when lead was not publicly disclosed. |
| `investors` | object\[] | Array of non-lead investor objects, same structure as `lead_investors`. May be absent. |

**Chart data structures:**

The `charts` object contains three keys, each with a `title`, `data` array, `source` attribution string, and `url` (pre-rendered chart image):

* `fundraising_line_chart` — quarterly deal count time series. Each data point: `{quarter: "Q3 '24", deals: 13}`
* `fundraising_stage_chart` — quarterly deal count broken out by stage (Seed Stage, Early Stage, Late Stage, Private Equity, Others). Each data point: `{quarter: "Q3 '24", stage: "Early Stage", deals: 3}`
* `fundraising_quarter_wise_chart` — quarterly total funding raised. Each data point uses a two-field value structure: `{quarter: "Q2 '24", funding: {value: 5.4, multiplier: 1000000000}}` — multiply `value × multiplier` to get the raw USD amount

> [!NOTE]
>
> The `fundraising_quarter_wise_chart` uses a `{value, multiplier}` pattern rather than raw integers to keep chart data readable. Always multiply `value × multiplier` before presenting amounts: `5.4 × 1,000,000,000 = $5.4B`. The `multiplier` is typically `1000000` (millions) or `1000000000` (billions), but always check rather than assuming.

### Download format options

| `file_type` | Description |
| - | - |
| `"json"` | Fully structured JSON — all sections, fields, and source citations. Best for programmatic processing, pipeline ingestion, or downstream analysis. |
| `"pdf"` | Formatted PDF report. Best for sharing with stakeholders who need a readable, printable document. |
| `"docx"` | Editable Word document. Best for teams that customise or annotate reports before distribution. |
| `"ppt"` | PowerPoint presentation with section slides. Best for IC presentations, LP updates, and conference briefings. |

***

## 6. Examples

### Basic industry research

Submit, poll, and download JSON — the standard three-step pattern.

```bash cURL theme={"system"}
# Step 1: Submit
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{"workflow": "industry_primer", "industry": "Electronics Manufacturing Services"}'

# Step 2: Poll (replace 123345 with your report_id)
curl --location 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=123345' \
  --header 'Authorization: Bearer '

# Step 3: Download
curl --location 'https://api.wokelo.ai/api/assets/download_report/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{"report_id": 123345, "file_type": "json"}'
```

```python Python theme={"system"}
import requests, time

API_KEY = ""
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Step 1: Submit
submit = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers=HEADERS,
    json={"workflow": "industry_primer", "industry": "Electronics Manufacturing Services"}
)
report_id = submit.json()["report_id"]
print(f"Submitted. report_id: {report_id}")

# Step 2: Poll
while True:
    status_r = requests.get(
        "https://api.wokelo.ai/api/assets/get_notebook_status/",
        headers=HEADERS,
        params={"report_id": report_id}
    )
    status = status_r.json().get("status")
    print(f"Status: {status}")
    if status == "Completed":
        break
    if status == "Failed":
        raise Exception("Report failed")
    time.sleep(15)

# Step 3: Download
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")
```

**Sample submission response:**

```json theme={"system"}
{
  "report_id": 123345
}
```

### Extracting key sections from the JSON report

Work with individual sections for targeted downstream processing.

```python theme={"system"}
# Assume report is already downloaded as a dict
report = result.json()

# --- Executive Summary narrative ---
exec_summary = report["Executive Summary"]["Executive Summary"]["summary"]["summary"]
print("EXECUTIVE SUMMARY (first 500 chars):")
print(exec_summary[:500])
print()

# --- Key Insights headlines ---
insights = report["Executive Summary"]["Key Insights"]["key_insights"]
print(f"KEY INSIGHTS ({len(insights)} total):")
for i, card in enumerate(insights, 1):
    print(f"  {i}. {card['insight']['title']}")
    print(f"     {card['insight']['paragraph'][:120]}...")
print()

# --- Industry overview summary ---
overview = report["Overview"]["Overview"]["industry_overview_details"]["summary"]
print("OVERVIEW (first 400 chars):")
print(overview[:400])
print()

# --- Trends and innovations ---
trends = report["Trends and innovations"]["Key trends and innovations"]["trend_and_innovations"]["summary"]
print(f"TRENDS SECTION LENGTH: {len(trends.split())} words")
print()

# --- Top fundraising deals (by size) ---
deals = report["Select transactions"]["Fundraising activities"]["fundraising"]["fundraising"]
sorted_deals = sorted(deals, key=lambda x: x.get("funding", 0), reverse=True)
print("TOP FUNDRAISING DEALS:")
for deal in sorted_deals[:5]:
    amount_m = deal["funding"] / 1_000_000
    lead = deal.get("lead_investors", [{}])[0].get("organization", {}).get("name", "undisclosed")
    print(f"  ${amount_m:.0f}M  {deal['organization']['name']}  ({deal['funding_type']})  Lead: {lead}")
```

### Parsing fundraising chart data

The quarterly funding chart uses a `{value, multiplier}` two-field pattern. Parse it correctly before presenting amounts.

```python theme={"system"}
charts = report["Select transactions"]["Fundraising activities"]["fundraising"]["fundraising"]["charts"]

# Deal count over time
print("Quarterly Deal Count:")
for pt in charts["fundraising_line_chart"]["data"]:
    print(f"  {pt['quarter']}: {pt['deals']} deals")

# Total funding over time (value × multiplier = USD)
print("\nQuarterly Total Funding:")
for pt in charts["fundraising_quarter_wise_chart"]["data"]:
    f = pt["funding"]
    usd = f["value"] * f["multiplier"]
    if usd >= 1e9:
        label = f"${usd / 1e9:.1f}B"
    else:
        label = f"${usd / 1e6:.0f}M"
    print(f"  {pt['quarter']}: {label}")

# Stage breakdown
print("\nDeals by Stage (most recent quarter):")
stage_data = charts["fundraising_stage_chart"]["data"]
latest_q = stage_data[-1]["quarter"]
latest = [pt for pt in stage_data if pt["quarter"] == latest_q]
for pt in latest:
    print(f"  {pt['stage']}: {pt['deals']} deals")
```

### Identifying top investors in a sector

Use the key investors sub-section to find the most active investors for deal sourcing or LP targeting.

```python theme={"system"}
investors = (
    report["Select transactions"]
    ["Fundraising activities"]
    ["key_investors_in_this_space"]
    ["key_investors_in_this_space"]
)

print(f"Top investors in {industry} ({len(investors)} total):\n")
for inv in investors[:10]:
    org  = inv["organization"]["name"]
    n    = inv["no_of_investments"]
    keys = ", ".join(inv.get("key_investments", []))
    print(f"  {org}  ({n} investments)")
    if keys:
        print(f"    Notable: {keys}")
```

### Batch research across a portfolio of sectors

Submit Industry Research for multiple sectors concurrently, then collect all reports.

```python theme={"system"}
import requests, time, concurrent.futures

API_KEY  = ""
HEADERS  = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

SECTORS = [
    "Warehouse Automation",
    "GLP-1 Obesity Drug Market",
    "Offshore Wind Energy",
    "Electronics Manufacturing Services",
    "Generative AI Infrastructure"
]

def submit_research(industry):
    r = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={"workflow": "industry_primer", "industry": industry}
    )
    return industry, r.json()["report_id"]

def poll_until_done(report_id, interval=20, timeout=900):
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=HEADERS,
            params={"report_id": report_id}
        )
        status = r.json().get("status")
        if status == "Completed":
            return True
        if status == "Failed":
            return False
        time.sleep(interval)
        elapsed += interval
    return False

def fetch_report(report_id):
    r = requests.post(
        "https://api.wokelo.ai/api/assets/download_report/",
        headers=HEADERS,
        json={"report_id": report_id, "file_type": "json"}
    )
    return r.json()

# Submit all concurrently
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool:
    futures = {pool.submit(submit_research, s): s for s in SECTORS}
    jobs = {}
    for future in concurrent.futures.as_completed(futures):
        sector, report_id = future.result()
        jobs[sector] = report_id
        print(f"Submitted: {sector} → report_id {report_id}")

# Poll and collect
reports = {}
for sector, report_id in jobs.items():
    ok = poll_until_done(report_id)
    if ok:
        reports[sector] = fetch_report(report_id)
        print(f"Collected: {sector}")
    else:
        print(f"Failed or timed out: {sector}")

print(f"\nCollected {len(reports)} / {len(SECTORS)} reports")
```

### Research with a custom file

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

```python theme={"system"}
import requests

API_KEY = ""
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Step 1: Upload the file
with open("internal_sector_brief.pdf", "rb") as f:
    upload_r = requests.post(
        "https://api.wokelo.ai/api/assets/upload/",
        headers=HEADERS,
        files={"files": ("internal_sector_brief.pdf", f, "application/pdf")}
    )
file_name = upload_r.json()["fileName"]

# Step 2: Submit report referencing the uploaded file
submit_r = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "workflow":     "industry_primer",
        "industry":     "Carbon Capture and Storage",
        "custom_files": [{"fileName": file_name}]
    }
)
report_id = submit_r.json()["report_id"]
print(f"Report with custom file submitted. report_id: {report_id}")
```

### Exporting as PPT for an IC presentation

```python theme={"system"}
import requests

HEADERS = {"Authorization": "Bearer "}

ppt_r = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": 123345, "file_type": "ppt"}
)

with open("ems_industry_research.pptx", "wb") as f:
    f.write(ppt_r.content)

print("Saved ems_industry_research.pptx")
```

***

## 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`, missing `industry`, or unrecognised `workflow` string. Check the `detail` field. Ensure `workflow` is exactly `"industry_primer"`. |
| `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 endpoint. Contact [support@wokelo.ai](mailto: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](mailto:support@wokelo.ai). |

**Handling a `"Failed"` report status:**

```python theme={"system"}
status_r = requests.get(
    "https://api.wokelo.ai/api/assets/get_notebook_status/",
    headers=HEADERS,
    params={"report_id": report_id}
)
if status_r.json().get("status") == "Failed":
    print(f"Report {report_id} failed. Resubmitting...")
    resubmit = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={"workflow": "industry_primer", "industry": "Warehouse Automation"}
    )
    new_id = resubmit.json()["report_id"]
    print(f"New report_id: {new_id}")
```

**Retry with exponential back-off on submission:**

```python theme={"system"}
import time, requests

def submit_with_retry(body, api_key, max_retries=3):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    for attempt in range(max_retries):
        try:
            r = requests.post(
                "https://api.wokelo.ai/api/workflow_manager/start/",
                headers=headers,
                json=body,
                timeout=30
            )
            if r.status_code == 429:
                time.sleep(2 ** attempt)
                continue
            r.raise_for_status()
            return r.json()["report_id"]
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
    raise Exception(f"Submission failed after {max_retries} attempts")
```

***

## 8. Best Practices

**Be specific and descriptive in the `industry` string — this is the single highest-impact parameter**

The `industry` field is a free-text string, and the specificity of what you write directly determines how focused and useful the report is. Vague inputs like `"technology"` or `"manufacturing"` produce broad, shallow reports. Specific, descriptive inputs produce deep, actionable sector coverage:

```python theme={"system"}
# ❌ Too broad — produces a generic, high-level report
body["industry"] = "Manufacturing"
body["industry"] = "Healthcare"
body["industry"] = "Finance"

# ✅ Specific — produces a focused, high-signal report
body["industry"] = "Electronics Manufacturing Services (EMS)"
body["industry"] = "GLP-1 Obesity Drug Market"
body["industry"] = "Offshore Wind Farm Development"
body["industry"] = "Carbon Capture and Storage Technology"
body["industry"] = "AI-Powered Revenue Cycle Management in Healthcare"
```

**`workflow` must always be `"industry_primer"` — not `"company_primer"`**

The `/api/workflow_manager/start/` endpoint is shared across all Workflow APIs. The `workflow` parameter is what distinguishes Industry Research from Company Research, Peer Comparison, and Custom Workflow. For Industry Research, it must be exactly `"industry_primer"`. Omitting it, misspelling it, or using `"company_primer"` returns a `400` error or generates the wrong report type.

**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 recover past `report_id` values. Store it to a database, log, or job queue entry as soon as the submission response is received:

```python theme={"system"}
report_id = response.json()["report_id"]
# ✅ Persist immediately before any further processing
save_to_db({"sector": industry, "report_id": report_id, "submitted_at": datetime.now()})
```

**Use 15–20 second polling intervals — not tight loops**

Industry Research reports typically complete in 2–5 minutes. Polling more frequently than every 15 seconds wastes rate limit budget without meaningfully reducing wait time. Use a progressive back-off for batch workloads:

```python theme={"system"}
for wait in [15, 15, 30, 30, 60, 60, 120]:
    time.sleep(wait)
    status = get_status(report_id)
    if status in ("Completed", "Failed"):
        break
```

**Parse the `{value, multiplier}` chart pattern defensively**

The quarterly funding chart uses a two-field encoding (`value` × `multiplier`) rather than raw integers. Always compute the actual amount rather than presenting `value` directly — a label of `"5.4"` instead of `"$5.4B"` will confuse stakeholders:

```python theme={"system"}
# ❌ Wrong — presents raw value without multiplier
amount = pt["funding"]["value"]                              # "5.4"

# ✅ Correct — applies the multiplier
amount_usd = pt["funding"]["value"] * pt["funding"]["multiplier"]  # 5400000000.0
```

**Check for absent `lead_investors` / `investors` before accessing them**

Both fields are optional in fundraising deal records — they are omitted entirely (not set to `[]`) when investor information was not publicly disclosed. Always use `.get()` with a default:

```python theme={"system"}
# ❌ KeyError risk when field is absent
lead_name = deal["lead_investors"][0]["organization"]["name"]

# ✅ Safe
leads = deal.get("lead_investors", [])
lead_name = leads[0]["organization"]["name"] if leads else "Undisclosed"
```

**Use `custom_files` to incorporate proprietary research**

The `custom_files` parameter causes Wokelo to synthesise your uploaded documents alongside its web research, producing a report that bridges your internal knowledge with current market data. This is particularly valuable for sectors where you already hold proprietary market maps, prior diligence, or analyst reports. Upload files via the [File Upload API](/supporting-apis-doc#file-upload) first, then pass the returned `fileName` values in the array.

**Use `"json"` for pipelines; `"ppt"` or `"pdf"` for human deliverables**

The JSON output contains all structured data, citation arrays, and chart data. Use it for any programmatic downstream work. The formatted outputs strip much of the metadata but are better suited for IC decks, LP updates, and conference briefings. A single `report_id` supports all four formats — you can download both JSON and PPT for the same report without resubmitting.

**Understand the difference from Industry News Monitoring**

Industry Research and Industry News Monitoring both accept a free-text topic and both cover a sector — but they are fundamentally different in output and use case. Industry News Monitoring returns a paginated list of real-time news articles (synchronous, no report generation). Industry Research returns a synthesised, structured intelligence report with market sizing, trend analysis, and transaction data (asynchronous, minutes to generate). Use Industry News Monitoring for ongoing real-time tracking; use Industry Research for periodic deep-dive primers and one-time sector coverage.

***

## 9. Related APIs

> **[Company Research](/company-research-doc)**
>
> The company-level equivalent — generates a sourced intelligence report on any specific company using the same async workflow pattern.

> **[Peer Comparison](/peer-comparison-doc)**
>
> Generate a structured side-by-side comparison of two or more companies across key dimensions in a single report.

> **[Industry Deep Intelligence](/industry-deep-intelligence-doc)**
>
> Synchronous alternative for structured industry intelligence — returns results directly without the report polling step.

> **[Industry News Monitoring](/industry-news-monitoring-doc)**
>
> Real-time news articles for any industry topic — synchronous, paginated, no polling required. Complements Industry Research for ongoing monitoring.

> **[Newsfeed](/newsfeed-doc)**
>
> Structured multi-industry news feed filtered by sentiment, geography, and event category — ideal for recurring monitoring pipelines.

> **[Supporting APIs](/supporting-apis-doc)**
>
> Report Status, Download Report, and File Upload — all used alongside Industry Research in the async workflow.

## 1. Overview

The Industry Research API generates an end-to-end sector intelligence report on any industry or market, covering market sizing, growth drivers, competitive dynamics, innovation trends, and recent transaction activity. 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](/supporting-apis-doc#report-status) endpoint and retrieve the finished report using the [Download Report](/supporting-apis-doc#download-report) endpoint.

**The three-step workflow:**

```text theme={"system"}
Step 1: POST /api/workflow_manager/start/         → returns report_id
Step 2: GET  /api/assets/get_notebook_status/     → poll until status = "Completed"
Step 3: POST /api/assets/download_report/         → retrieve JSON / PDF / DOCX / PPT
```

The completed report is structured into five major sections, each returned as a named key in the JSON output:

* **Executive Summary** — multi-paragraph narrative covering market size, growth drivers, regional dynamics, technology trends, supply chain, and regulatory landscape; fully source-cited with 20–30+ references
* **Key Insights** — 8–10 analyst-style insight cards, each with a headline metric, supporting data paragraph, and multi-point commentary with citations
* **Overview** — structured description of the industry — definition, key offerings, market segments, and core problems the sector solves
* **Trends and Innovations** — detailed synthesis of technological, operational, and strategic trends reshaping the industry, with named company examples and quantified data points
* **Select Transactions** — fundraising activity data for companies in the space, including per-deal records with investor details, funding stage, and amounts; quarterly deal-count and total-funding charts; and a ranked list of key investors

**Common use cases:**

* **Thesis development for new sectors** — generate a sourced, structured primer on any industry before committing diligence resources to it
* **LP and IC briefing decks** — export as PPT or PDF for sector updates, investment committee presentations, or fund strategy reviews
* **Market entry and expansion research** — understand market size, regional dynamics, and competitive structure for any industry in minutes
* **Deal sourcing context** — use the Select Transactions section to identify active fundraising companies and leading investors in a sector
* **Competitive intelligence** — track innovation trends and strategic partnerships across a sector to identify white spaces and disruption vectors
* **Custom report augmentation** — supply `custom_files` to layer proprietary internal research or market data on top of Wokelo's synthesis

> [!NOTE]
>
> 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](/how-async-apis-work) for a full explanation of the polling lifecycle.

***

## 2. Quick Start

**Step 1 — Submit the report request**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "industry_primer",
    "industry": "Warehouse Automation"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "industry_primer",
        "industry": "Warehouse Automation"
    }
)
report_id = response.json()["report_id"]
print(f"Report submitted. report_id: {report_id}")
```

**Step 2 — Poll for completion**

```python theme={"system"}
import time, requests

def wait_for_report(report_id, api_key, poll_interval=15, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=headers,
            params={"report_id": report_id}
        )
        status = r.json().get("status", "")
        print(f"[{elapsed}s] Status: {status}")
        if status == "Completed":
            return True
        if status == "Failed":
            raise Exception(f"Report {report_id} failed")
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise TimeoutError(f"Report {report_id} did not complete within {timeout}s")

wait_for_report(report_id, api_key="")
```

**Step 3 — Download the report**

```python theme={"system"}
# Fetch as JSON for programmatic processing
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")

# Or download as a formatted document
ppt_result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "ppt"}
)
with open("industry_research.pptx", "wb") as f:
    f.write(ppt_result.content)
```

***

## 3. Authentication

All requests must include a **Bearer token** in the `Authorization` HTTP header.

```text theme={"system"}
Authorization: Bearer 
```

API tokens are issued from your Wokelo account. Navigate to **Settings → API Keys** in the Wokelo dashboard to generate or rotate a key. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access.

> [!WARNING]
>
> 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**

```text theme={"system"}
POST https://api.wokelo.ai/api/workflow_manager/start/
```

All parameters are passed as JSON in the request body.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflow` | string | **Required** | Must always be `"industry_primer"`. This fixed value tells Wokelo's workflow engine to run the Industry Research report. Do not confuse with `"company_primer"` (Company Research) or `"peer_comparison"` (Peer Comparison). |
| `industry` | string | **Required** | Free-text description of the industry or sector to research. Specificity drives report quality — see Best Practices for guidance on phrasing. Examples: `"Warehouse Automation"`, `"Electronics Manufacturing Services"`, `"GLP-1 Obesity Drug Market"`, `"Offshore Wind Energy"`. |
| `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](/supporting-apis-doc#file-upload). Use this to incorporate proprietary market research, analyst reports, or internal sector notes. |

> [!NOTE]
>
> Unlike Company Research, Industry Research has no `permalink`, `website`, or `workbook_name` parameters. The `industry` string is the only identifier and the primary driver of report scope and quality.

**Full request example:**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "industry_primer",
    "industry": "Electronics Manufacturing Services"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "industry_primer",
        "industry": "Electronics Manufacturing Services"
    }
)
print(response.json())   # {"report_id": 123345}
```

***

## 5. Response

### Submission response

The initial POST returns immediately with a single field:

```json theme={"system"}
{
  "report_id": 123345
}
```

| Field | Type | Description |
| - | - | - |
| `report_id` | integer | Unique identifier for this report job. Use it with the Report Status and Download Report endpoints to track and retrieve the completed report. Store this value immediately — it is the only handle to your report. |

### Report status response

Poll `GET /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

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 Industry Research are:

**Executive Summary**

Contains two sub-keys:

* `Executive Summary` → `summary` object with a `source` array of citation objects (`id`, `title`, `url`, `publisher`, `date`) and a `summary` field containing a full markdown-formatted multi-section narrative (Overview, Market Dynamics and Growth Drivers, Regional Market Leadership, Technological Innovation, Supply Chain, Regulatory Environment)
* `Key Insights` → `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

**Overview**

Contains an `industry_overview_details` object with a `source` array and a `summary` field covering: industry definition, how it operates, key offerings (as named and described categories), market segments, and problems being solved.

**Trends and Innovations**

Contains a `trend_and_innovations` object with a `source` array and a `summary` field — a long-form markdown narrative organised by innovation themes (e.g. Advanced Materials, Cybersecurity, Printed Electronics, AI Automation, Predictive Maintenance, Sustainability, Adaptive Manufacturing, Strategic Partnerships).

**Select Transactions**

Contains two sub-keys:

* `Fundraising activities` → `fundraising` object with:
  * `fundraising` array — individual deal records (see below)
  * `key_investors_in_this_space` → `key_investors_in_this_space` array — ranked investor records with `organization` (name, logo, url, permalink), `no_of_investments`, and `key_investments` (array of strings)
  * `sources` array — data attribution (typically Crunchbase)
  * `charts` object — three chart data structures (see below)

**Fundraising deal record fields:**

| Field | Type | Description |
| - | - | - |
| `organization` | object | Company that raised. Contains `name`, `url` (Wokelo dashboard link), `logo`, and `permalink`. |
| `funding` | integer | Raw USD amount raised (e.g. `30000000` for \$30M). Always a numeric integer — never an empty string. |
| `funding_type` | string | Round type. Examples: `"Series A"`, `"Series B"`, `"Seed"`, `"Debt-Funded"`, `"Non-Equity Assistance"`, `"Corporate-Funded"`, `"Private Equity"`. |
| `date` | string | Close date in `DD-Mon-YYYY` format (e.g. `"23-Dec-2025"`). |
| `product_category` | string | Short label for the company's product or service area. |
| `lead_investors` | object\[] | Array of lead investor objects, each with an `organization` sub-object (`name`, `url`, `logo`, `permalink`). May be absent when lead was not publicly disclosed. |
| `investors` | object\[] | Array of non-lead investor objects, same structure as `lead_investors`. May be absent. |

**Chart data structures:**

The `charts` object contains three keys, each with a `title`, `data` array, `source` attribution string, and `url` (pre-rendered chart image):

* `fundraising_line_chart` — quarterly deal count time series. Each data point: `{quarter: "Q3 '24", deals: 13}`
* `fundraising_stage_chart` — quarterly deal count broken out by stage (Seed Stage, Early Stage, Late Stage, Private Equity, Others). Each data point: `{quarter: "Q3 '24", stage: "Early Stage", deals: 3}`
* `fundraising_quarter_wise_chart` — quarterly total funding raised. Each data point uses a two-field value structure: `{quarter: "Q2 '24", funding: {value: 5.4, multiplier: 1000000000}}` — multiply `value × multiplier` to get the raw USD amount

> [!NOTE]
>
> The `fundraising_quarter_wise_chart` uses a `{value, multiplier}` pattern rather than raw integers to keep chart data readable. Always multiply `value × multiplier` before presenting amounts: `5.4 × 1,000,000,000 = $5.4B`. The `multiplier` is typically `1000000` (millions) or `1000000000` (billions), but always check rather than assuming.

### Download format options

| `file_type` | Description |
| - | - |
| `"json"` | Fully structured JSON — all sections, fields, and source citations. Best for programmatic processing, pipeline ingestion, or downstream analysis. |
| `"pdf"` | Formatted PDF report. Best for sharing with stakeholders who need a readable, printable document. |
| `"docx"` | Editable Word document. Best for teams that customise or annotate reports before distribution. |
| `"ppt"` | PowerPoint presentation with section slides. Best for IC presentations, LP updates, and conference briefings. |

***

## 6. Examples

### Basic industry research

Submit, poll, and download JSON — the standard three-step pattern.

```bash cURL theme={"system"}
# Step 1: Submit
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{"workflow": "industry_primer", "industry": "Electronics Manufacturing Services"}'

# Step 2: Poll (replace 123345 with your report_id)
curl --location 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=123345' \
  --header 'Authorization: Bearer '

# Step 3: Download
curl --location 'https://api.wokelo.ai/api/assets/download_report/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{"report_id": 123345, "file_type": "json"}'
```

```python Python theme={"system"}
import requests, time

API_KEY = ""
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Step 1: Submit
submit = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers=HEADERS,
    json={"workflow": "industry_primer", "industry": "Electronics Manufacturing Services"}
)
report_id = submit.json()["report_id"]
print(f"Submitted. report_id: {report_id}")

# Step 2: Poll
while True:
    status_r = requests.get(
        "https://api.wokelo.ai/api/assets/get_notebook_status/",
        headers=HEADERS,
        params={"report_id": report_id}
    )
    status = status_r.json().get("status")
    print(f"Status: {status}")
    if status == "Completed":
        break
    if status == "Failed":
        raise Exception("Report failed")
    time.sleep(15)

# Step 3: Download
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")
```

**Sample submission response:**

```json theme={"system"}
{
  "report_id": 123345
}
```

### Extracting key sections from the JSON report

Work with individual sections for targeted downstream processing.

```python theme={"system"}
# Assume report is already downloaded as a dict
report = result.json()

# --- Executive Summary narrative ---
exec_summary = report["Executive Summary"]["Executive Summary"]["summary"]["summary"]
print("EXECUTIVE SUMMARY (first 500 chars):")
print(exec_summary[:500])
print()

# --- Key Insights headlines ---
insights = report["Executive Summary"]["Key Insights"]["key_insights"]
print(f"KEY INSIGHTS ({len(insights)} total):")
for i, card in enumerate(insights, 1):
    print(f"  {i}. {card['insight']['title']}")
    print(f"     {card['insight']['paragraph'][:120]}...")
print()

# --- Industry overview summary ---
overview = report["Overview"]["Overview"]["industry_overview_details"]["summary"]
print("OVERVIEW (first 400 chars):")
print(overview[:400])
print()

# --- Trends and innovations ---
trends = report["Trends and innovations"]["Key trends and innovations"]["trend_and_innovations"]["summary"]
print(f"TRENDS SECTION LENGTH: {len(trends.split())} words")
print()

# --- Top fundraising deals (by size) ---
deals = report["Select transactions"]["Fundraising activities"]["fundraising"]["fundraising"]
sorted_deals = sorted(deals, key=lambda x: x.get("funding", 0), reverse=True)
print("TOP FUNDRAISING DEALS:")
for deal in sorted_deals[:5]:
    amount_m = deal["funding"] / 1_000_000
    lead = deal.get("lead_investors", [{}])[0].get("organization", {}).get("name", "undisclosed")
    print(f"  ${amount_m:.0f}M  {deal['organization']['name']}  ({deal['funding_type']})  Lead: {lead}")
```

### Parsing fundraising chart data

The quarterly funding chart uses a `{value, multiplier}` two-field pattern. Parse it correctly before presenting amounts.

```python theme={"system"}
charts = report["Select transactions"]["Fundraising activities"]["fundraising"]["fundraising"]["charts"]

# Deal count over time
print("Quarterly Deal Count:")
for pt in charts["fundraising_line_chart"]["data"]:
    print(f"  {pt['quarter']}: {pt['deals']} deals")

# Total funding over time (value × multiplier = USD)
print("\nQuarterly Total Funding:")
for pt in charts["fundraising_quarter_wise_chart"]["data"]:
    f = pt["funding"]
    usd = f["value"] * f["multiplier"]
    if usd >= 1e9:
        label = f"${usd / 1e9:.1f}B"
    else:
        label = f"${usd / 1e6:.0f}M"
    print(f"  {pt['quarter']}: {label}")

# Stage breakdown
print("\nDeals by Stage (most recent quarter):")
stage_data = charts["fundraising_stage_chart"]["data"]
latest_q = stage_data[-1]["quarter"]
latest = [pt for pt in stage_data if pt["quarter"] == latest_q]
for pt in latest:
    print(f"  {pt['stage']}: {pt['deals']} deals")
```

### Identifying top investors in a sector

Use the key investors sub-section to find the most active investors for deal sourcing or LP targeting.

```python theme={"system"}
investors = (
    report["Select transactions"]
    ["Fundraising activities"]
    ["key_investors_in_this_space"]
    ["key_investors_in_this_space"]
)

print(f"Top investors in {industry} ({len(investors)} total):\n")
for inv in investors[:10]:
    org  = inv["organization"]["name"]
    n    = inv["no_of_investments"]
    keys = ", ".join(inv.get("key_investments", []))
    print(f"  {org}  ({n} investments)")
    if keys:
        print(f"    Notable: {keys}")
```

### Batch research across a portfolio of sectors

Submit Industry Research for multiple sectors concurrently, then collect all reports.

```python theme={"system"}
import requests, time, concurrent.futures

API_KEY  = ""
HEADERS  = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

SECTORS = [
    "Warehouse Automation",
    "GLP-1 Obesity Drug Market",
    "Offshore Wind Energy",
    "Electronics Manufacturing Services",
    "Generative AI Infrastructure"
]

def submit_research(industry):
    r = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={"workflow": "industry_primer", "industry": industry}
    )
    return industry, r.json()["report_id"]

def poll_until_done(report_id, interval=20, timeout=900):
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=HEADERS,
            params={"report_id": report_id}
        )
        status = r.json().get("status")
        if status == "Completed":
            return True
        if status == "Failed":
            return False
        time.sleep(interval)
        elapsed += interval
    return False

def fetch_report(report_id):
    r = requests.post(
        "https://api.wokelo.ai/api/assets/download_report/",
        headers=HEADERS,
        json={"report_id": report_id, "file_type": "json"}
    )
    return r.json()

# Submit all concurrently
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool:
    futures = {pool.submit(submit_research, s): s for s in SECTORS}
    jobs = {}
    for future in concurrent.futures.as_completed(futures):
        sector, report_id = future.result()
        jobs[sector] = report_id
        print(f"Submitted: {sector} → report_id {report_id}")

# Poll and collect
reports = {}
for sector, report_id in jobs.items():
    ok = poll_until_done(report_id)
    if ok:
        reports[sector] = fetch_report(report_id)
        print(f"Collected: {sector}")
    else:
        print(f"Failed or timed out: {sector}")

print(f"\nCollected {len(reports)} / {len(SECTORS)} reports")
```

### Research with a custom file

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

```python theme={"system"}
import requests

API_KEY = ""
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Step 1: Upload the file
with open("internal_sector_brief.pdf", "rb") as f:
    upload_r = requests.post(
        "https://api.wokelo.ai/api/assets/upload/",
        headers=HEADERS,
        files={"files": ("internal_sector_brief.pdf", f, "application/pdf")}
    )
file_name = upload_r.json()["fileName"]

# Step 2: Submit report referencing the uploaded file
submit_r = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "workflow":     "industry_primer",
        "industry":     "Carbon Capture and Storage",
        "custom_files": [{"fileName": file_name}]
    }
)
report_id = submit_r.json()["report_id"]
print(f"Report with custom file submitted. report_id: {report_id}")
```

### Exporting as PPT for an IC presentation

```python theme={"system"}
import requests

HEADERS = {"Authorization": "Bearer "}

ppt_r = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": 123345, "file_type": "ppt"}
)

with open("ems_industry_research.pptx", "wb") as f:
    f.write(ppt_r.content)

print("Saved ems_industry_research.pptx")
```

***

## 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`, missing `industry`, or unrecognised `workflow` string. Check the `detail` field. Ensure `workflow` is exactly `"industry_primer"`. |
| `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 endpoint. Contact [support@wokelo.ai](mailto: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](mailto:support@wokelo.ai). |

**Handling a `"Failed"` report status:**

```python theme={"system"}
status_r = requests.get(
    "https://api.wokelo.ai/api/assets/get_notebook_status/",
    headers=HEADERS,
    params={"report_id": report_id}
)
if status_r.json().get("status") == "Failed":
    print(f"Report {report_id} failed. Resubmitting...")
    resubmit = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={"workflow": "industry_primer", "industry": "Warehouse Automation"}
    )
    new_id = resubmit.json()["report_id"]
    print(f"New report_id: {new_id}")
```

**Retry with exponential back-off on submission:**

```python theme={"system"}
import time, requests

def submit_with_retry(body, api_key, max_retries=3):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    for attempt in range(max_retries):
        try:
            r = requests.post(
                "https://api.wokelo.ai/api/workflow_manager/start/",
                headers=headers,
                json=body,
                timeout=30
            )
            if r.status_code == 429:
                time.sleep(2 ** attempt)
                continue
            r.raise_for_status()
            return r.json()["report_id"]
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
    raise Exception(f"Submission failed after {max_retries} attempts")
```

***

## 8. Best Practices

**Be specific and descriptive in the `industry` string — this is the single highest-impact parameter**

The `industry` field is a free-text string, and the specificity of what you write directly determines how focused and useful the report is. Vague inputs like `"technology"` or `"manufacturing"` produce broad, shallow reports. Specific, descriptive inputs produce deep, actionable sector coverage:

```python theme={"system"}
# ❌ Too broad — produces a generic, high-level report
body["industry"] = "Manufacturing"
body["industry"] = "Healthcare"
body["industry"] = "Finance"

# ✅ Specific — produces a focused, high-signal report
body["industry"] = "Electronics Manufacturing Services (EMS)"
body["industry"] = "GLP-1 Obesity Drug Market"
body["industry"] = "Offshore Wind Farm Development"
body["industry"] = "Carbon Capture and Storage Technology"
body["industry"] = "AI-Powered Revenue Cycle Management in Healthcare"
```

**`workflow` must always be `"industry_primer"` — not `"company_primer"`**

The `/api/workflow_manager/start/` endpoint is shared across all Workflow APIs. The `workflow` parameter is what distinguishes Industry Research from Company Research, Peer Comparison, and Custom Workflow. For Industry Research, it must be exactly `"industry_primer"`. Omitting it, misspelling it, or using `"company_primer"` returns a `400` error or generates the wrong report type.

**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 recover past `report_id` values. Store it to a database, log, or job queue entry as soon as the submission response is received:

```python theme={"system"}
report_id = response.json()["report_id"]
# ✅ Persist immediately before any further processing
save_to_db({"sector": industry, "report_id": report_id, "submitted_at": datetime.now()})
```

**Use 15–20 second polling intervals — not tight loops**

Industry Research reports typically complete in 2–5 minutes. Polling more frequently than every 15 seconds wastes rate limit budget without meaningfully reducing wait time. Use a progressive back-off for batch workloads:

```python theme={"system"}
for wait in [15, 15, 30, 30, 60, 60, 120]:
    time.sleep(wait)
    status = get_status(report_id)
    if status in ("Completed", "Failed"):
        break
```

**Parse the `{value, multiplier}` chart pattern defensively**

The quarterly funding chart uses a two-field encoding (`value` × `multiplier`) rather than raw integers. Always compute the actual amount rather than presenting `value` directly — a label of `"5.4"` instead of `"$5.4B"` will confuse stakeholders:

```python theme={"system"}
# ❌ Wrong — presents raw value without multiplier
amount = pt["funding"]["value"]                              # "5.4"

# ✅ Correct — applies the multiplier
amount_usd = pt["funding"]["value"] * pt["funding"]["multiplier"]  # 5400000000.0
```

**Check for absent `lead_investors` / `investors` before accessing them**

Both fields are optional in fundraising deal records — they are omitted entirely (not set to `[]`) when investor information was not publicly disclosed. Always use `.get()` with a default:

```python theme={"system"}
# ❌ KeyError risk when field is absent
lead_name = deal["lead_investors"][0]["organization"]["name"]

# ✅ Safe
leads = deal.get("lead_investors", [])
lead_name = leads[0]["organization"]["name"] if leads else "Undisclosed"
```

**Use `custom_files` to incorporate proprietary research**

The `custom_files` parameter causes Wokelo to synthesise your uploaded documents alongside its web research, producing a report that bridges your internal knowledge with current market data. This is particularly valuable for sectors where you already hold proprietary market maps, prior diligence, or analyst reports. Upload files via the [File Upload API](/supporting-apis-doc#file-upload) first, then pass the returned `fileName` values in the array.

**Use `"json"` for pipelines; `"ppt"` or `"pdf"` for human deliverables**

The JSON output contains all structured data, citation arrays, and chart data. Use it for any programmatic downstream work. The formatted outputs strip much of the metadata but are better suited for IC decks, LP updates, and conference briefings. A single `report_id` supports all four formats — you can download both JSON and PPT for the same report without resubmitting.

**Understand the difference from Industry News Monitoring**

Industry Research and Industry News Monitoring both accept a free-text topic and both cover a sector — but they are fundamentally different in output and use case. Industry News Monitoring returns a paginated list of real-time news articles (synchronous, no report generation). Industry Research returns a synthesised, structured intelligence report with market sizing, trend analysis, and transaction data (asynchronous, minutes to generate). Use Industry News Monitoring for ongoing real-time tracking; use Industry Research for periodic deep-dive primers and one-time sector coverage.

***

## 9. Related APIs

> **[Company Research](/company-research-doc)**
>
> The company-level equivalent — generates a sourced intelligence report on any specific company using the same async workflow pattern.

> **[Peer Comparison](/peer-comparison-doc)**
>
> Generate a structured side-by-side comparison of two or more companies across key dimensions in a single report.

> **[Industry Deep Intelligence](/industry-deep-intelligence-doc)**
>
> Synchronous alternative for structured industry intelligence — returns results directly without the report polling step.

> **[Industry News Monitoring](/industry-news-monitoring-doc)**
>
> Real-time news articles for any industry topic — synchronous, paginated, no polling required. Complements Industry Research for ongoing monitoring.

> **[Newsfeed](/newsfeed-doc)**
>
> Structured multi-industry news feed filtered by sentiment, geography, and event category — ideal for recurring monitoring pipelines.

> **[Supporting APIs](/supporting-apis-doc)**
>
> Report Status, Download Report, and File Upload — all used alongside Industry Research in the async workflow.


# Introduction
Source: https://docs.wokelo.ai/introduction

Wokelo's API suite is purpose-built for developers building dealmaking AI infrastructure. It delivers structured, processed intelligence at the quality standard investment and advisory workflows demand. The underlying data is purpose-built for AI pipelines:

* Entities are resolved across a proprietary database of **20M+ private and public companies**.
* News signals are deduplicated across **1,000+ curated sources.**
* **Custom parameters and scoring logic** can be defined at query time.
* Every output is **agent-native, source-traced, and ready to plug** directly into your models, agents,  and workflows without additional processing.

## API Products

### **Discovery**

> **[Market Map](/market-map-doc)**
>
> Ranked, filtered company lists with custom parameters.

> **[Target Screening](/target-screening-doc)**
>
> Scored acquisition targets with custom filtering logic.

> **[Buyer Screening](/buyer-screening-doc)**
>
> Scored strategic and financial buyers with custom logic.

> **[Competitor List](/competitor-list-doc)**
>
> Find competitors of a given company.

> **[M\&A Activity](/acquisitions-doc)**
>
> Obtain in-depth acquisition activities of a given company.

> **[Fundraising Activity](/fundraise-doc)**
>
> Obtain funding activity, investor landscape, and funding stage analysis.

### **Workflow Automation**

> **[Company Research](/company-research-doc)**
>
> Trigger Wokelo's company research workflows and return in any format.

> **[Industry Research](/industry-research-doc)**
>
> Trigger Wokelo's industry research workflows, return in any format.

> **[Peer Comparison](/peer-comparison-doc)**
>
> Trigger Wokelo's peer comparison workflows and return in any format.

> **[Custom Workflow](/custom-workflow-automation-doc)**
>
> Trigger custom research workflows and return in any format.

## API structure

Wokelo’s API follows two primary patterns depending on the complexity of the operation:

**Synchronous APIs (instant response)**

* Company Search — Returns matching companies immediately in the HTTP response

**Asynchronous APIs (submit request, poll for status, retrieve results)**

* All Workflow Automation and Discovery APIs return a report\_id
* Poll for status, then retrieve results when complete. For request\_id, use Request result API to view the results. For report\_id, use Download Report API to download the report.

Eg. Company Research API will return a report\_id as a response. One has to use Download Report API to view the report output.

```json theme={"system"}
{
    "report_id": 123345
}
```

## Estimated Time

| **API** | **Approximate Time** |
| :- | :- |
| Market Map | 10-15 mins |
| Target Screening | 10-15 mins |
| Buyer Screening | 10-15 mins |
| Competitor List | 10-15 mins |
| M\&A Activity | 10-15 mins |
| Fundraising Activity | 10-15 mins |
| Company Research | 20-25 mins |
| Industry Research | 20-25 mins |
| Peer Comparison | 15-20 mins |
| Custom Workflow | Custom |


# ISO Country Codes
Source: https://docs.wokelo.ai/iso-country-codes



3-letter codes used in the country parameter across all Wokelo API endpoints.

| **Country** | **Alpha-3 code** |
| :- | :- |
| Afghanistan | AFG |
| Albania | ALB |
| Algeria | DZA |
| American Samoa | ASM |
| Andorra | AND |
| Angola | AGO |
| Anguilla | AIA |
| Antarctica | ATA |
| Antigua and Barbuda | ATG |
| Argentina | ARG |
| Armenia | ARM |
| Aruba | ABW |
| Australia | AUS |
| Austria | AUT |
| Azerbaijan | AZE |
| Bahamas (the) | BHS |
| Bahrain | BHR |
| Bangladesh | BGD |
| Barbados | BRB |
| Belarus | BLR |
| Belgium | BEL |
| Belize | BLZ |
| Benin | BEN |
| Bermuda | BMU |
| Bhutan | BTN |
| Bolivia (Plurinational State of) | BOL |
| Bonaire, Sint Eustatius and Saba | BES |
| Bosnia and Herzegovina | BIH |
| Botswana | BWA |
| Bouvet Island | BVT |
| Brazil | BRA |
| British Indian Ocean Territory (the) | IOT |
| Brunei Darussalam | BRN |
| Bulgaria | BGR |
| Burkina Faso | BFA |
| Burundi | BDI |
| Cabo Verde | CPV |
| Cambodia | KHM |
| Cameroon | CMR |
| Canada | CAN |
| Cayman Islands (the) | CYM |
| Central African Republic (the) | CAF |
| Chad | TCD |
| Chile | CHL |
| China | CHN |
| Christmas Island | CXR |
| Cocos (Keeling) Islands (the) | CCK |
| Colombia | COL |
| Comoros (the) | COM |
| Congo (the Democratic Republic of the) | COD |
| Congo (the) | COG |
| Cook Islands (the) | COK |
| Costa Rica | CRI |
| Croatia | HRV |
| Cuba | CUB |
| Curaçao | CUW |
| Cyprus | CYP |
| Czechia | CZE |
| Côte d'Ivoire | CIV |
| Denmark | DNK |
| Djibouti | DJI |
| Dominica | DMA |
| Dominican Republic (the) | DOM |
| Ecuador | ECU |
| Egypt | EGY |
| El Salvador | SLV |
| Equatorial Guinea | GNQ |
| Eritrea | ERI |
| Estonia | EST |
| Eswatini | SWZ |
| Ethiopia | ETH |
| Falkland Islands (the) \[Malvinas] | FLK |
| Faroe Islands (the) | FRO |
| Fiji | FJI |
| Finland | FIN |
| France | FRA |
| French Guiana | GUF |
| French Polynesia | PYF |
| French Southern Territories (the) | ATF |
| Gabon | GAB |
| Gambia (the) | GMB |
| Georgia | GEO |
| Germany | DEU |
| Ghana | GHA |
| Gibraltar | GIB |
| Greece | GRC |
| Greenland | GRL |
| Grenada | GRD |
| Guadeloupe | GLP |
| Guam | GUM |
| Guatemala | GTM |
| Guernsey | GGY |
| Guinea | GIN |
| Guinea-Bissau | GNB |
| Guyana | GUY |
| Haiti | HTI |
| Heard Island and McDonald Islands | HMD |
| Holy See (the) | VAT |
| Honduras | HND |
| Hong Kong | HKG |
| Hungary | HUN |
| Iceland | ISL |
| India | IND |
| Indonesia | IDN |
| Iran (Islamic Republic of) | IRN |
| Iraq | IRQ |
| Ireland | IRL |
| Isle of Man | IMN |
| Israel | ISR |
| Italy | ITA |
| Jamaica | JAM |
| Japan | JPN |
| Jersey | JEY |
| Jordan | JOR |
| Kazakhstan | KAZ |
| Kenya | KEN |
| Kiribati | KIR |
| Korea (the Democratic People's Republic of) | PRK |
| Korea (the Republic of) | KOR |
| Kuwait | KWT |
| Kyrgyzstan | KGZ |
| Lao People's Democratic Republic (the) | LAO |
| Latvia | LVA |
| Lebanon | LBN |
| Lesotho | LSO |
| Liberia | LBR |
| Libya | LBY |
| Liechtenstein | LIE |
| Lithuania | LTU |
| Luxembourg | LUX |
| Macao | MAC |
| Madagascar | MDG |
| Malawi | MWI |
| Malaysia | MYS |
| Maldives | MDV |
| Mali | MLI |
| Malta | MLT |
| Marshall Islands (the) | MHL |
| Martinique | MTQ |
| Mauritania | MRT |
| Mauritius | MUS |
| Mayotte | MYT |
| Mexico | MEX |
| Micronesia (Federated States of) | FSM |
| Moldova (the Republic of) | MDA |
| Monaco | MCO |
| Mongolia | MNG |
| Montenegro | MNE |
| Montserrat | MSR |
| Morocco | MAR |
| Mozambique | MOZ |
| Myanmar | MMR |
| Namibia | NAM |
| Nauru | NRU |
| Nepal | NPL |
| Netherlands (the) | NLD |
| New Caledonia | NCL |
| New Zealand | NZL |
| Nicaragua | NIC |
| Niger (the) | NER |
| Nigeria | NGA |
| Niue | NIU |
| Norfolk Island | NFK |
| Northern Mariana Islands (the) | MNP |
| Norway | NOR |
| Oman | OMN |
| Pakistan | PAK |
| Palau | PLW |
| Palestine, State of | PSE |
| Panama | PAN |
| Papua New Guinea | PNG |
| Paraguay | PRY |
| Peru | PER |
| Philippines (the) | PHL |
| Pitcairn | PCN |
| Poland | POL |
| Portugal | PRT |
| Puerto Rico | PRI |
| Qatar | QAT |
| Republic of North Macedonia | MKD |
| Romania | ROU |
| Russian Federation (the) | RUS |
| Rwanda | RWA |
| Réunion | REU |
| Saint Barthélemy | BLM |
| Saint Helena, Ascension and Tristan da Cunha | SHN |
| Saint Kitts and Nevis | KNA |
| Saint Lucia | LCA |
| Saint Martin (French part) | MAF |
| Saint Pierre and Miquelon | SPM |
| Saint Vincent and the Grenadines | VCT |
| Samoa | WSM |
| San Marino | SMR |
| Sao Tome and Principe | STP |
| Saudi Arabia | SAU |
| Senegal | SEN |
| Serbia | SRB |
| Seychelles | SYC |
| Sierra Leone | SLE |
| Singapore | SGP |
| Sint Maarten (Dutch part) | SXM |
| Slovakia | SVK |
| Slovenia | SVN |
| Solomon Islands | SLB |
| Somalia | SOM |
| South Africa | ZAF |
| South Georgia and the South Sandwich Islands | SGS |
| South Sudan | SSD |
| Spain | ESP |
| Sri Lanka | LKA |
| Sudan (the) | SDN |
| Suriname | SUR |
| Svalbard and Jan Mayen | SJM |
| Sweden | SWE |
| Switzerland | CHE |
| Syrian Arab Republic | SYR |
| Taiwan (Province of China) | TWN |
| Tajikistan | TJK |
| Tanzania, United Republic of | TZA |
| Thailand | THA |
| Timor-Leste | TLS |
| Togo | TGO |
| Tokelau | TKL |
| Tonga | TON |
| Trinidad and Tobago | TTO |
| Tunisia | TUN |
| Turkey | TUR |
| Turkmenistan | TKM |
| Turks and Caicos Islands (the) | TCA |
| Tuvalu | TUV |
| Uganda | UGA |
| Ukraine | UKR |
| United Arab Emirates (the) | ARE |
| United Kingdom of Great Britain and Northern Ireland (the) | GBR |
| United States Minor Outlying Islands | UMI |
| United States of America (the) | USA |
| Uruguay | URY |
| Uzbekistan | UZB |
| Vanuatu | VUT |
| Venezuela (Bolivarian Republic of) | VEN |
| Viet Nam | VNM |
| Virgin Islands (British) | VGB |
| Virgin Islands (U.S.) | VIR |
| Wallis and Futuna | WLF |
| Western Sahara | ESH |
| Yemen | YEM |
| Zambia | ZMB |
| Zimbabwe | ZWE |
| Åland Islands | ALA |


# Market Map
Source: https://docs.wokelo.ai/market-map

POST https://api.wokelo.ai/api/workflow_manager/start/

## Overview

The Market Map API generates a long list of companies operating in a given market (e.g., *"warehouse automation"*), enriched with structured data. You can refine the output with a detailed query, sample companies, geography, company type, employee count, funding stage, financial filters, and more.

Market Map runs as a workflow. Set `workflow` to `agentic_mm` in the request body to start one. The request returns a `report_id`, which you then use to track completion and export the results.

## Endpoint Details

* Method: POST
* Endpoint: `/api/workflow_manager/start/`

## Authentication Requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

### Body Parameters

**topic** `string` *required*

The market or product category to map (e.g. `"warehouse automation"`)

**workflow** `string` *required*

The workflow to run. Must be `"agentic_mm"` for Market Map.

**workbook\_name** `string` *required*

Name of the workbook that will hold the generated market map (e.g. `"warehouse automation"`)

**advanced\_settings** `object`

Filter parameters object. All filters live inside `advanced_settings`. Include the object in every request, and send empty values (`""`, `[]`) for any filter you do not want to apply.

**detailed\_query** `string`

A more descriptive query to refine the market map scope

**companies** `string[]`

Permalinks of representative companies or their complete URLs to anchor the market map.

**geography** `string[]`

Geographic scope. Pass `["Worldwide"]` for no geographic restriction, or a list of ISO country codes (e.g. `["USA", "GBR"]`).

**company\_type** `string`

Type of company to include. Accepted values: `"private"`, `"public"`, `"all"`

**employee\_count** `string[]`

Filter by employee headcount range. Pass an empty array to include all headcounts.

Supported array values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+`

**founded\_year** `object`

Filter by company founding year.

**from** `integer`

Minimum founding year (inclusive), e.g. `2010`

**to** `integer`

Maximum founding year (inclusive), e.g. `2020`

**funding\_stage** `string[]`

Filter by funding stage (e.g. `"Series A"`, `"Series B"`). Pass an empty array to include all stages.

Supported array values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A`, `Series B`, `Series C`, `Series D`, `Series E`, `Series F`, `Series G`, `Series H`, `Series I`, `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others`

**total\_funding** `object`

Filter by total funding amount raised (in USD).

**from** `number`

Minimum total funding in USD, e.g. `1000000`

**to** `number`

Maximum total funding in USD, e.g. `50000000`

**total\_funding\_include\_blanks** `boolean`

When `true`, companies with no reported total funding are included in the results alongside companies that match the `total_funding` range.

**last\_funding\_round** `object`

Filter by last funding round amount (in USD).

**from** `number`

Minimum last funding round in USD, e.g. `500000`

**to** `number`

Maximum last funding round in USD, e.g. `20000000`

**revenue** `object`

Filter by annual revenue (in USD).

**from** `number`

Minimum annual revenue in USD, e.g. `500000`

**to** `number`

Maximum annual revenue in USD, e.g. `10000000`

**ebitda** `object`

Filter by EBITDA (in USD).

**from** `number`

Minimum EBITDA in USD

**to** `number`

Maximum EBITDA in USD

**net\_income** `object`

Filter by net income (in USD).

**from** `number`

Minimum net income in USD

**to** `number`

Maximum net income in USD

**ev\_ebitda** `object`

Filter by EV/EBITDA multiple.

**from** `number`

Minimum EV/EBITDA multiple

**to** `number`

Maximum EV/EBITDA multiple

```json Basic request theme={"system"}
{
  "topic": "warehouse automation",
  "workflow": "agentic_mm",
  "workbook_name": "warehouse automation",
  "advanced_settings": {
    "detailed_query": "warehouse automation",
    "companies": [],
    "company_type": "all",
    "geography": ["Worldwide"],
    "employee_count": [],
    "funding_stage": [],
    "total_funding_include_blanks": true
  }
}
```

```json Request with filters theme={"system"}
{
  "topic": "warehouse automation",
  "workflow": "agentic_mm",
  "workbook_name": "warehouse automation",
  "advanced_settings": {
    "detailed_query": "Robotics and software platforms for warehouse automation",
    "companies": [],
    "company_type": "private",
    "geography": ["USA", "GBR"],
    "employee_count": ["51-100", "101-250"],
    "funding_stage": ["Series A", "Series B"],
    "total_funding": {
      "from": 1000000,
      "to": 50000000
    },
    "total_funding_include_blanks": false
  }
}
```

### Response

A successful response returns a `report_id` that identifies the market map report.

#### Successful Response Fields

**report\_id** `integer`

Unique identifier for the report created by this request. Use it to track completion and to download the results (see below).

```json 200 theme={"system"}
{
  "report_id": 117253
}
```

## Tracking Completion and Exporting Results

Market Map generation is asynchronous. After you receive a `report_id`:

1. Use `/api/assets/get_notebook_status/` to track completion of the report.
2. Once the report is complete, use `/api/assets/download_report/` to export the results.


# Market Map
Source: https://docs.wokelo.ai/market-map-doc

Generate a long list of companies in a defined market, enriched with firmographic, funding and financial data and scored for relevance.

## 1. Overview

The Market Map API generates a long list of companies operating in a defined market, enriched with firmographic, funding and financial data. Given a market topic (e.g. *"warehouse automation"*) and optional filters, the AI pipeline evaluates each candidate against the market thesis and returns a list with relevance scores and per-company commentary.

This is an **asynchronous API**. Starting the workflow returns a `report_id`, which you use to track completion and export the results. See [How Async APIs work](/how-async-apis-work).

Each company includes firmographics, product profile, funding and headcount, financials (for public companies), M\&A history, an `Overall Score` (1 to 10) and a `Commentary` explaining its relevance to the market.

**Common use cases:**

* **Deal sourcing**: build a scored target universe for a vertical or thesis
* **Corporate strategy and M\&A**: map the landscape for a market entry or build-vs-buy analysis
* **Market research**: generate an exhaustive vendor set for benchmarking

***

## 2. Quick Start

**Step 1: Start the workflow**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "warehouse automation",
    "workflow": "agentic_mm",
    "workbook_name": "warehouse automation",
    "advanced_settings": {
      "detailed_query": "warehouse automation",
      "companies": [],
      "company_type": "all",
      "geography": ["Worldwide"],
      "employee_count": [],
      "funding_stage": [],
      "total_funding_include_blanks": true
    }
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "topic": "warehouse automation",
        "workflow": "agentic_mm",
        "workbook_name": "warehouse automation",
        "advanced_settings": {
            "detailed_query": "warehouse automation",
            "companies": [],
            "company_type": "all",
            "geography": ["Worldwide"],
            "employee_count": [],
            "funding_stage": [],
            "total_funding_include_blanks": True
        }
    }
)
print(response.json()["report_id"])
```

The response contains a `report_id`.

**Step 2: Track completion**

Use `/api/assets/get_notebook_status/` with the `report_id` to check whether the report has completed.

**Step 3: Export results**

Once the report is complete, use `/api/assets/download_report/` with the `report_id` to export the results.

***

## 3. Authentication

Include a Bearer token in the `Authorization` header of every request.

```text theme={"system"}
Authorization: Bearer 
```

Obtain a token from the `/auth/token/` endpoint using the client id and client secret under **Account Details → API Credentials** in the Wokelo dashboard. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access.

> [!WARNING]
>
> Never expose your token in client-side code or public repositories.

***

## 4. Request Reference

**Endpoint**

```text theme={"system"}
POST https://api.wokelo.ai/api/workflow_manager/start/
```

The request body is JSON. Include `advanced_settings` in every request and send empty values (`""`, `[]`) for filters you do not want to apply.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `topic` | string | **Required** | The market or product category to map (e.g. `"warehouse automation"`). |
| `workflow` | string | **Required** | Must be `"agentic_mm"`. |
| `workbook_name` | string | **Required** | Name of the workbook that holds the generated report. |
| `advanced_settings` | object | Optional | Filter parameters. All filters below live inside this object. |
| `advanced_settings.detailed_query` | string | Optional | A more descriptive query that refines the market scope. |
| `advanced_settings.companies` | string\[] | Optional | Permalinks or full URLs of representative companies to anchor the search. |
| `advanced_settings.geography` | string\[] | Optional | `["Worldwide"]` for no restriction, or ISO country codes (e.g. `["USA", "GBR"]`). |
| `advanced_settings.company_type` | string | Optional | `"private"`, `"public"` or `"all"`. |
| `advanced_settings.employee_count` | string\[] | Optional | Headcount bands. Empty array includes all. Values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+`. |
| `advanced_settings.founded_year` | object | Optional | Object with `from` and/or `to` (integer years, inclusive). |
| `advanced_settings.funding_stage` | string\[] | Optional | Empty array includes all. Values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A` to `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others`. |
| `advanced_settings.total_funding` | object | Optional | Object with `from` and/or `to`, in USD. |
| `advanced_settings.total_funding_include_blanks` | boolean | Optional | When `true`, companies with no reported total funding are included. |
| `advanced_settings.last_funding_round`, `.revenue`, `.ebitda`, `.net_income` | object | Optional | Each accepts `from` and/or `to`, in USD. Revenue, EBITDA and net income work best with `company_type: "public"`. |
| `advanced_settings.ev_ebitda` | object | Optional | Object with `from` and/or `to` (EV/EBITDA multiple). |

***

## 5. Response

### Workflow start response

```json theme={"system"}
{
  "report_id": 117253
}
```

| Field | Type | Description |
| - | - | - |
| `report_id` | integer | Unique identifier of the report. Use it to track completion and export results. |

### Report output fields

| Field | Description |
| - | - |
| `Permalink`, `Name`, `Website` | Wokelo company identifier, display name and primary domain. |
| `HQ City`, `HQ Country`, `HQ Continent`, `Founded` | Headquarters location and founding year. |
| `Type`, `Operating Status` | Ownership type (`Public` or `Private`) and status (e.g. `Operating`, `Acquired`, `IPO`). |
| `Product Category`, `Core Offering`, `Product Catalog` | Primary product category, AI-generated description of the core business, and key products. |
| `Employees (Crunchbase)`, `Employees (LinkedIn)` | Headcount band and numeric headcount. |
| `Funding Stage`, `Total Funding`, `Last Funding Date`, `Key Investors` | Funding profile. Total funding is in USD. Typically empty for public companies. |
| `Revenue`, `EBITDA`, `Net Income`, `Market Cap`, `Enterprise Value`, `Ticker`, margins and multiples | Financial data in USD, primarily populated for public companies. |
| `Acquisitions`, `Investments` | Past acquisitions (with year) and notable investments. May be empty. |
| `Overall Score`, `Commentary` | Relevance score (1 to 10) for the queried market, and an AI-written explanation of the fit. |

***

## 6. Examples

### Filtered market map

Private warehouse automation companies in the USA and UK, 51 to 250 employees, Series A or B, with \$1M to \$50M total funding.

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "warehouse automation",
    "workflow": "agentic_mm",
    "workbook_name": "warehouse automation",
    "advanced_settings": {
      "detailed_query": "Robotics and software platforms for warehouse automation",
      "companies": [],
      "company_type": "private",
      "geography": ["USA", "GBR"],
      "employee_count": ["51-100", "101-250"],
      "funding_stage": ["Series A", "Series B"],
      "total_funding": {
        "from": 1000000,
        "to": 50000000
      },
      "total_funding_include_blanks": false
    }
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "topic": "warehouse automation",
        "workflow": "agentic_mm",
        "workbook_name": "warehouse automation",
        "advanced_settings": {
            "detailed_query": "Robotics and software platforms for warehouse automation",
            "companies": [],
            "company_type": "private",
            "geography": ["USA", "GBR"],
            "employee_count": ["51-100", "101-250"],
            "funding_stage": ["Series A", "Series B"],
            "total_funding": {
                "from": 1000000,
                "to": 50000000
            },
            "total_funding_include_blanks": False
        }
    }
)
print(response.json()["report_id"])
```

***


# News categories
Source: https://docs.wokelo.ai/news-categories



Accepted values for the category parameters in GET/company/news.

| Serial No. | Value |
| - | - |
| 1 | Others |
| 2 | Strategic Development |
| 3 | Capital Markets & Transactions |
| 4 | Leadership & Governance |
| 5 | Workforce & Talent |
| 6 | Financial Results & Performance |
| 7 | Regulatory & Compliance |
| 8 | Macro & Market Environment |
| 9 | Market Dynamic |
| 10 | Industry Disruption & Innovation |
| 11 | Risk & Crisis Events |
| 12 | Product Launches & Enhancements |
| 13 | Partnerships & Alliances |
| 14 | Geographic Expansion |
| 15 | Operational Milestones |
| 16 | Market Share & Positioning |
| 17 | Digital Transformation |
| 18 | Brand & Marketing Initiatives |
| 19 | Research, Development & Innovation |
| 20 | Sustainability & ESG |
| 21 | Pricing & Commercial Strategy |
| 22 | Equity Fund-Raising |
| 23 | Debt Financing |
| 24 | Mergers & Acquisitions |
| 25 | Divestitures & Asset Sales |
| 26 | IPOs & Follow-on Offerings |
| 27 | SPAC Deals & De-SPACs |
| 28 | Secondary Transactions |
| 29 | Shareholder Returns (Buybacks & Dividends) |
| 30 | Valuation Events |
| 31 | Deal Flow & Volume Statistics |
| 32 | Public-to-Private/Take-Private |
| 33 | C-Suite Appointments & Departures |
| 34 | Board Composition & Changes |
| 35 | Succession Planning |
| 36 | Organisational Restructuring |
| 37 | Executive Commentary & Interviews |
| 38 | Strategic Hiring |
| 39 | Workforce Reductions |
| 40 | Compensation & Benefits |
| 41 | Culture & Workplace Practices |
| 42 | Talent-Market Dynamics |
| 43 | Earnings Releases |
| 44 | Revenue & Growth Metrics |
| 45 | Profitability & Margins |
| 46 | Cash Flow & Capital Expenditure |
| 47 | Guidance & Forecast Revisions |
| 48 | Credit-Rating Actions |
| 49 | Sector Performance Dashboards |
| 50 | Regulatory Approvals & Certifications |
| 51 | Policy & Legislative Changes |
| 52 | Legal Proceedings & Litigation |
| 53 | Compliance & Reporting Updates |
| 54 | Intellectual Property |
| 55 | Antitrust & Competition |
| 56 | Data Privacy & Cybersecurity Regulation |
| 57 | Tax & Accounting Rules |
| 58 | Economic Indicators |
| 59 | Monetary Policy |
| 60 | Fiscal Policy |
| 61 | Trade, Tariffs & Sanctions |
| 62 | Consumer Behaviour & Spending |
| 63 | Labor-Market Statistics |
| 64 | Sector Outlook & Forecasts |
| 65 | Market Indices Performance |
| 66 | Institutional Flows & Positioning |
| 67 | Sector Rotation |
| 68 | Volatility & Risk Appetite |
| 69 | FX & Commodity Pricing |
| 70 | Liquidity Conditions |
| 71 | Investor Sentiment |
| 72 | Emerging Technologies |
| 73 | Technology Adoption & Disruption |
| 74 | Business-Model Evolution |
| 75 | Competitive Threats |
| 76 | Market-Structure Changes |
| 77 | Geopolitical Risk |
| 78 | Public-Health Crises |
| 79 | Natural Disasters |
| 80 | Operational Disruptions |
| 81 | Cybersecurity Incidents |
| 82 | Reputational Damage |
| 83 | Financial Distress & Restructuring |
| 84 | Supply-Chain Disruptions |
| 85 | Awards, Rankings & Recognitions |
| 86 | Conflicts of Interest & Related-Party Transactions |


# Notebook Configuration
Source: https://docs.wokelo.ai/notebook-configuration

POST /api/wkl/notebook/configuration/
Retrieves and returns the settings originally configured while initiating the report. Pass the `notebook_id` (report ID) to get all initial configuration attributes used when triggering the workflow.

## Overview

Retrieves and returns the settings you originally configured while initiating the report.

## Endpoint Details

* **Method:** POST
* **Endpoint:** `api/wkl/notebook/configuration/`

## Authentication requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

### Request Parameters

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

#### Body Parameters

**notebook\_id** `integer` *required*

Report ID of the notebook for which the configuration is to be retrieved

## Response

Successful response will contain all the initial configuration attributes added while triggering the workflow.


# OneDrive
Source: https://docs.wokelo.ai/onedrive



## Overview

Connect your OneDrive to Wokelo and seamlessly convert your existing documents into AI-powered research insights. Through a secure authentication connection, select files directly from OneDrive and feed them into our research agents to generate actionable analysis—no data migration required.

## Integration Capabilities

* **Comprehensive file support** — Word, PowerPoint, Excel, PDF, text, CSV.
* **Preserves your workflow** — Works with existing folder structures without reorganization
* **Enterprise security** — Fully encrypted and SOC 2 Type II compliant

## Use-cases

* **Due diligence research** — Analyze CIMs, board decks, and KPI files for comprehensive company assessments
* **Custom workflow integration** — Incorporate OneDrive documents into tailored research processes
* **Intelligent document querying** — Ask natural language questions like "What is the latest ARR by region?" across your file library
* **Report generation** — Create investor briefs, DDQs, and presentation decks directly from selected OneDrive content

## How it works

Selecting files from OneDrive is a seamless step while running your workflows on Wokelo

* On the file upload step, click on OneDrive’s icon
  * If you’re uploading files for the first time, you might be redirected to a login screen to authenticate your account.

![Image](https://mintcdn.com/wokeloai-7cd44985/8250xbq19cn-lch7/images/image-56.png?fit=max\&auto=format\&n=8250xbq19cn-lch7\&q=85\&s=480b1aa9227432e921bb7e5df9b9262c)

* This brings up the files you have available in OneDrive. Select the relevant files you want to be included in your research, and click on Select in the bottom right corner to upload the selected files.

![Image](https://mintcdn.com/wokeloai-7cd44985/8250xbq19cn-lch7/images/image-57.png?fit=max\&auto=format\&n=8250xbq19cn-lch7\&q=85\&s=c12a4e57ce87ca10f6588bec2636c5d9)

* Once uploaded, you would see a list of files that will be used in the workflow. Click Next to trigger the report with the relevant files.

![Image](https://mintcdn.com/wokeloai-7cd44985/8250xbq19cn-lch7/images/image-58.png?fit=max\&auto=format\&n=8250xbq19cn-lch7\&q=85\&s=aef3491524f54c8159eeed932abd2a7c)

[Integrate OneDrive →](/contact)


# Overview
Source: https://docs.wokelo.ai/overview



We have two kinds of APIs:

1. **Discovery:** Workflows for specific use cases such as generating a market map, screening targets or buyers, finding competitors, and tracking M\&A and fundraising activity. Uses Wokelo's database and alternative data.
2. **Workflow Automation:** Full-length research reports, including Wokelo's built-in workflows (Company Research, Industry Research, Peer Comparison) and your own custom workflows.

| API | Type |
| :- | :- |
| Market Map | Discovery |
| Target Screening | Discovery |
| Buyer Screening | Discovery |
| Competitor List | Discovery |
| M\&A Activity | Discovery |
| Fundraise Activity | Discovery |
| Company Research | Workflow Automation |
| Industry Research | Workflow Automation |
| Peer Comparison | Workflow Automation |
| Custom Workflow | Workflow Automation |

Both types are asynchronous and follow the same pattern. Starting a workflow returns a `report_id`. Use it to track the report status and then download the output in your preferred format, such as PDF, DOCX or JSON. See [How Async APIs work](/how-async-apis-work) for details, and [Choosing the right API](/choosing-the-right-api) to find the right API for your use case.


# Peer Comparison
Source: https://docs.wokelo.ai/peer-comparison

POST https://api.wokelo.ai/api/workflow_manager/start/

## Overview

Generates a comprehensive comparison of up to 5 companies. The report analyzes multiple dimensions including company fundamentals and firmographics, product offerings and business models, employee reviews and satisfaction, hiring trends and workforce data, and online presence and market visibility.

## Endpoint Details

* **Method:** POST
* **Endpoint:** `/api/workflow_manager/start/`

## Authentication requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

### Request Parameters

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

#### Body Parameters

**workflow** `string` *required*

`player_comparison`

**websites** `An array of strings` *required*

Array of company websites to compare

**workbook\_name** `(string)`

Name with which the workbook will be saved

**Sample payload**

```json theme={"system"}
{
    "workflow": "player_comparison",
    "websites": [
        "stripe.com",
        "paypal.com"
    ],
    "workbook_name": "Player Comparison Report"
}
```

## Response

Successful response will include the report\_id of the Peer Comparison report

### Successful Response Fields

**report\_id** `integer`

Report id for the initiated Peer Comparison Report

```json 200 theme={"system"}
{
    "report_id": 1002345
}
```


# Peer Comparison
Source: https://docs.wokelo.ai/peer-comparison-doc

Generate a comprehensive side-by-side benchmarking report for 2–5 companies — covering firmographics, financials, product offerings, feature matrices, business models, employee sentiment, hiring trends, and online visibility — as structured JSON, PDF, DOCX, or PPT.

## 1. Overview

The Peer Comparison API generates a comprehensive multi-dimensional benchmarking report for 2 to 5 companies simultaneously. Unlike Company Research (which covers a single company in depth), this API produces a purpose-built side-by-side analysis designed to surface competitive differentiation across every major dimension — from financials and product features to employee sentiment and hiring velocity.

This is an **asynchronous POST API** — submitting a request returns a `report_id` immediately. You then poll for completion using the [Report Status](/supporting-apis-doc#report-status) endpoint and retrieve the finished report using the [Download Report](/supporting-apis-doc#download-report) endpoint.

**The three-step workflow:**

```text theme={"system"}
Step 1: POST /api/workflow_manager/start/         → returns report_id
Step 2: GET  /api/assets/get_notebook_status/     → poll until status = "Completed"
Step 3: POST /api/assets/download_report/         → retrieve JSON / PDF / DOCX / PPT
```

Companies are identified by **website URL** rather than permalink. Up to 5 URLs can be passed in a single request.

The completed report is structured into several named sections, each returned as a top-level key in the JSON output:

* **Firmographics** — one structured card per company: firmographic details (industry, HQ, headcount, funding stage, total funding), and a full financial suite including revenue, EBITDA, net income, EPS, market cap, and valuation multiples (EV/Sales, EV/EBITDA, P/E)
* **Product offerings** — two views of the competitive product landscape: a narrative `product_offerings` array (one entry per product capability area per company) and a `key_product_features` feature matrix (yes/no cells per company per feature category, with a structured `company_result_mapping`)
* **Business model** — structured area/details comparison across Revenue & Pricing, Operational Setup, Value Proposition, and Customer Segments — one entry per company per area
* **Additional sections** — depending on data availability, reports may also include Employee Reviews (sentiment and satisfaction data), Hiring Trends (role-level headcount and velocity signals), and Online Presence (SEO and web visibility metrics)

**Common use cases:**

* **Competitive diligence packages** — compare a target company against 3–4 direct peers before an IC presentation, with a single report covering every relevant dimension
* **Market map benchmarking** — identify which players offer which product capabilities using the feature matrix, and surface white-space gaps
* **Buy-side deal screening** — compare multiple acquisition candidates side by side on financials, product scope, and headcount to quickly eliminate or prioritise targets
* **Portfolio company positioning** — benchmark a portfolio company against its peers on hiring velocity, employee satisfaction, and online visibility to identify operational underperformance
* **Investor presentations** — export as PPT or PDF to embed peer comparison tables directly in LP updates, conference decks, or deal memos

> [!NOTE]
>
> This API is asynchronous. The initial POST returns a `report_id` only — not the report content. Report generation typically completes in 3–7 minutes for a 5-company comparison. See [How Async APIs work](/how-async-apis-work) for a full explanation of the polling lifecycle.

***

## 2. Quick Start

**Step 1 — Submit the report request**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "player_comparison",
    "websites": [
      "https://we.are.expensify.com/",
      "https://ramp.com/",
      "https://www.airbase.com/"
    ],
    "workbook_name": "Spend Management Peer Comparison"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "player_comparison",
        "websites": [
            "https://we.are.expensify.com/",
            "https://ramp.com/",
            "https://www.airbase.com/"
        ],
        "workbook_name": "Spend Management Peer Comparison"
    }
)
report_id = response.json()["report_id"]
print(f"Report submitted. report_id: {report_id}")
```

**Step 2 — Poll for completion**

```python theme={"system"}
import time, requests

def wait_for_report(report_id, api_key, poll_interval=20, timeout=900):
    headers = {"Authorization": f"Bearer {api_key}"}
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=headers,
            params={"report_id": report_id}
        )
        status = r.json().get("status", "")
        print(f"[{elapsed}s] Status: {status}")
        if status == "Completed":
            return True
        if status == "Failed":
            raise Exception(f"Report {report_id} failed")
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise TimeoutError(f"Report {report_id} did not complete within {timeout}s")

wait_for_report(report_id, api_key="")
```

**Step 3 — Download the report**

```python theme={"system"}
# Fetch as JSON for programmatic processing
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")

# Or download as a formatted document
ppt_result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers={"Authorization": "Bearer "},
    json={"report_id": report_id, "file_type": "ppt"}
)
with open("peer_comparison.pptx", "wb") as f:
    f.write(ppt_result.content)
```

***

## 3. Authentication

All requests must include a **Bearer token** in the `Authorization` HTTP header.

```text theme={"system"}
Authorization: Bearer 
```

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](mailto:support@wokelo.ai) if you do not yet have API access.

> [!WARNING]
>
> 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**

```text theme={"system"}
POST https://api.wokelo.ai/api/workflow_manager/start/
```

All parameters are passed as JSON in the request body.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflow` | string | **Required** | Must always be `"player_comparison"`. This is distinct from `"company_primer"` (Company Research) and `"industry_primer"` (Industry Research). Using the wrong value submits the wrong report type or returns a `400` error. |
| `websites` | string\[] | **Required** | Array of company website URLs to compare. Accepts 2–5 entries. Both bare domain format (`"stripe.com"`) and full URL format (`"https://www.stripe.com"`) are accepted. All companies must be web-resolvable — Wokelo uses the URL to identify each company in its knowledge base. |
| `workbook_name` | string | Optional | Label for the generated report workbook. Defaults to a generic name if omitted. Using a descriptive name (e.g. `"Payments Competitive Landscape Q2 2026"`) makes the report easier to identify in subsequent Report Status or 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](/supporting-apis-doc#file-upload). |

> [!NOTE]
>
> The minimum number of websites is 2 and the maximum is 5. Passing a single URL or more than 5 will return a `400 Bad Request`. All URLs must be for different companies — duplicate entries will not produce meaningful comparisons.

**Full request example:**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "player_comparison",
    "websites": [
      "https://we.are.expensify.com/",
      "https://ramp.com/",
      "https://www.airbase.com/",
      "http://www.expensya.com/",
      "https://payhawk.com/"
    ],
    "workbook_name": "Spend Management Peer Comparison"
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "workflow": "player_comparison",
        "websites": [
            "https://we.are.expensify.com/",
            "https://ramp.com/",
            "https://www.airbase.com/",
            "http://www.expensya.com/",
            "https://payhawk.com/"
        ],
        "workbook_name": "Spend Management Peer Comparison"
    }
)
print(response.json())   # {"report_id": 1002345}
```

***

## 5. Response

### Submission response

The initial POST returns immediately with a single field:

```json theme={"system"}
{
  "report_id": 1002345
}
```

| 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

Poll `GET /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

When you call Download Report with `"file_type": "json"`, the response is a nested JSON object with section names as top-level keys. The primary sections are:

**Firmographics**

Path: `report["Firmographics"]["Firmographic"]["firmographics"]["firmographics"]`

An array of company objects, one per company in the same order as the submitted `websites` array. Each object contains:

* `organization` — `name`, `logo` (URL), `url` (Wokelo dashboard link)
* `details` — firmographic fields:
  * `industry` (string), `product_category` (string), `founded_year` (string), `hq` (string), `company_type` (`"public"`, `"private"`, `"startup"`)
  * `employees_in_crunchbase` (string range, e.g. `"1001-5000"`), `website` (string)
  * `total_funding` (integer USD, e.g. `2967000000` for \$2.97B) — may be `0` for unfunded/bootstrapped companies
  * `last_funding_round` — object with `currency`, optional `value` (integer USD), optional `date` (`YYYY-MM-DD`), and `round` (e.g. `"Series E"`, `"Public"`, `"Acquired"`)
  * `financials` — a dict of financial metric objects. Each metric (e.g. `"Total revenue"`, `"EBITDA"`, `"Market cap"`) contains `period` (`YYYY-MM-DD`), `v` (numeric value or `null`), and `currency`. For public companies, this also includes `"Ticker"` (string), `"EV/Sales"`, `"EV/EBITDA"`, `"P/E"`, `"EV/EBIT"`, margin fields, and EPS fields. Private companies typically have fewer or no `financials` fields.
* `description` — paragraph description of the company's product and market position
* `sources` array — data attribution (Crunchbase, S\&P CapIQ, Wokelo Synthesis)

**Product offerings**

Path: `report["Product offerings"]["Product offerings"]`

Contains two parallel views of the competitive product landscape:

`product_offerings` — array of area objects, one per product capability area (e.g. "Expense Management & Reporting", "Corporate Card & Payment Solutions"). Each area object has an `area` label and a `details` array with one entry per company, containing:

* `company_name`, `permalink`, `area_details` (prose description of that company's capability in this area), and `sources` array

`key_product_features` — a structured feature matrix with:

* `rows` — array of feature objects. Each object has `category_name` (the feature being compared), `commentary` (a sentence summarising the competitive picture), and `company_names` (array of `{result, company_name, company_permalink}` objects where `result` is `"yes"` or `"no"`)
* `company_result_mapping` — dict keyed by permalink with `"yes"` / `"no"` values — useful for programmatic table generation
* `columns` — ordered list of permalinks matching the companies in the comparison

**Business model**

Path: `report["Business model"]["Business model"]["business_model"]`

Array of area objects following the same `area` / `details` pattern as product offerings, covering: Revenue & Pricing, Operational Setup, Value Proposition, and Customer Segments.

> [!NOTE]
>
> The `financials` dict in Firmographics uses `"v"` as the value key (not `"value"`). It can be `null` for metrics that are unavailable or not applicable (e.g. P/E for a company with negative earnings). Always check for `null` before performing arithmetic on financial fields.

### Financial field notes

Financial data in the `details.financials` dict uses a consistent structure:

```json theme={"system"}
"Total revenue": {
  "period": "2024-12-31",
  "v": 139236000.0,
  "currency": "USD"
}
```

Raw values are in the base unit (USD, not millions). To convert:

```python theme={"system"}
# Revenue in millions
revenue_m = financials["Total revenue"]["v"] / 1_000_000  # → 139.2

# EBITDA margin is stored as a fraction, not a percentage
ebitda_margin_pct = financials["EBITDA margin (%)"]["v"] * 100  # → 0.068%
```

Note that `EBITDA margin (%)` and `Net margin (%)` store fractional values (e.g. `0.0675` = 6.75%), not percentage values. Multiply by 100 before displaying.

### Download format options

| `file_type` | Description |
| - | - |
| `"json"` | Fully structured JSON — all sections, fields, and source citations. Best for programmatic processing, CRM enrichment, or pipeline ingestion. |
| `"pdf"` | Formatted PDF with comparison tables and charts. Best for sharing with stakeholders. |
| `"docx"` | Editable Word document. Best for analysts who customise reports before distribution. |
| `"ppt"` | PowerPoint presentation. Best for IC decks, LP updates, and deal memos. |

***

## 6. Examples

### Basic peer comparison — three companies

```bash cURL theme={"system"}
# Step 1: Submit
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow": "player_comparison",
    "websites": ["stripe.com", "paypal.com", "square.com"],
    "workbook_name": "Payments Competitive Landscape"
  }'

# Step 2: Poll (replace 1002345 with your report_id)
curl --location 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=1002345' \
  --header 'Authorization: Bearer '

# Step 3: Download
curl --location 'https://api.wokelo.ai/api/assets/download_report/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{"report_id": 1002345, "file_type": "json"}'
```

```python Python theme={"system"}
import requests, time

API_KEY = ""
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Step 1: Submit
submit = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers=HEADERS,
    json={
        "workflow": "player_comparison",
        "websites": ["stripe.com", "paypal.com", "square.com"],
        "workbook_name": "Payments Competitive Landscape"
    }
)
report_id = submit.json()["report_id"]
print(f"Submitted. report_id: {report_id}")

# Step 2: Poll
while True:
    r = requests.get(
        "https://api.wokelo.ai/api/assets/get_notebook_status/",
        headers=HEADERS,
        params={"report_id": report_id}
    )
    status = r.json().get("status")
    print(f"Status: {status}")
    if status == "Completed":
        break
    if status == "Failed":
        raise Exception("Report failed")
    time.sleep(20)

# Step 3: Download
result = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": report_id, "file_type": "json"}
)
report = result.json()
print(f"Sections: {list(report.keys())}")
```

**Sample submission response:**

```json theme={"system"}
{
  "report_id": 1002345
}
```

### Extracting and displaying firmographic data

Parse the firmographics section to build a comparison table of key metrics across all companies.

```python theme={"system"}
# Assume report is already downloaded as a dict
report = result.json()

companies = (
    report["Firmographics"]
    ["Firmographic"]
    ["firmographics"]
    ["firmographics"]
)

print(f"{'Company':<20} {'Type':<12} {'HQ':<30} {'Employees':<20} {'Total Funding'}")
print("-" * 100)

for co in companies:
    name    = co["organization"]["name"]
    details = co["details"]
    funding = details.get("total_funding", 0)
    fund_str = f"${funding / 1e9:.1f}B" if funding >= 1e9 else (f"${funding / 1e6:.0f}M" if funding > 0 else "—")

    print(
        f"{name:<20} "
        f"{details.get('company_type', '—'):<12} "
        f"{details.get('hq', '—'):<30} "
        f"{details.get('employees_in_crunchbase', '—'):<20} "
        f"{fund_str}"
    )
```

### Comparing financial metrics across public and private companies

Financial data is only populated for public companies and well-covered private ones. Always guard against `null` values.

```python theme={"system"}
def safe_financial(financials, key, scale=1, as_percent=False):
    """Safely extract a financial metric, handling null and missing fields."""
    field = financials.get(key, {})
    v = field.get("v")
    if v is None:
        return "N/A"
    if as_percent:
        return f"{v * 100:.1f}%"
    if scale == 1e9:
        return f"${v / 1e9:.1f}B"
    if scale == 1e6:
        return f"${v / 1e6:.0f}M"
    return f"{v:.2f}"

companies = (
    report["Firmographics"]["Firmographic"]["firmographics"]["firmographics"]
)

print(f"{'Company':<20} {'Revenue':<15} {'EBITDA Margin':<18} {'Net Margin':<15} {'Market Cap'}")
print("-" * 90)

for co in companies:
    name = co["organization"]["name"]
    fin  = co["details"].get("financials", {})
    print(
        f"{name:<20} "
        f"{safe_financial(fin, 'Total revenue', scale=1e6):<15} "
        f"{safe_financial(fin, 'EBITDA margin (%)', as_percent=True):<18} "
        f"{safe_financial(fin, 'Net margin (%)', as_percent=True):<15} "
        f"{safe_financial(fin, 'Market cap', scale=1e9)}"
    )
```

### Reading the feature matrix

The `key_product_features` matrix is the most structured part of the report and is ideal for programmatic table generation.

```python theme={"system"}
product_data = (
    report["Product offerings"]
    ["Product offerings"]
    ["key_product_features"]
)

columns    = product_data["columns"]    # ordered list of permalinks
rows       = product_data["rows"]

# Build company-name lookup from firmographics
company_names = {
    co["details"].get("website", "").replace("https://", "").replace("http://", "").rstrip("/"): co["organization"]["name"]
    for co in report["Firmographics"]["Firmographic"]["firmographics"]["firmographics"]
}

# Print matrix
header = f"{'Feature':<40} " + "  ".join(f"{c[:12]:<12}" for c in columns)
print(header)
print("-" * (40 + 14 * len(columns)))

for row in rows:
    feature = row["category_name"]
    mapping = row["company_result_mapping"]
    cells   = "  ".join(f"{'✓' if mapping.get(c) == 'yes' else '✗':<12}" for c in columns)
    print(f"{feature:<40} {cells}")
    print(f"  {row['commentary'][:100]}...")
    print()
```

### Extracting business model comparison

Parse the Business model section to compare revenue models and customer segments across all peers.

```python theme={"system"}
business_model = (
    report["Business model"]
    ["Business model"]
    ["business_model"]
)

for area_obj in business_model:
    area = area_obj["area"]
    print(f"\n{'='*60}")
    print(f"  {area}")
    print('='*60)
    for detail in area_obj["details"]:
        name  = detail["company_name"]
        desc  = detail["area_details"]
        print(f"\n  {name}:")
        print(f"    {desc[:200]}...")
```

### Batch comparisons across multiple competitive sets

Run comparisons for several competitive landscapes and collect all reports.

```python theme={"system"}
import requests, time, concurrent.futures

API_KEY  = ""
HEADERS  = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

COMPARISONS = {
    "payments":    ["stripe.com", "paypal.com", "square.com", "adyen.com"],
    "crm":         ["salesforce.com", "hubspot.com", "pipedrive.com", "zoho.com"],
    "spend_mgmt":  ["ramp.com", "expensify.com", "brex.com", "airbase.com"],
}

def submit_comparison(name, websites):
    r = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={
            "workflow":      "player_comparison",
            "websites":      websites,
            "workbook_name": f"{name} Peer Comparison"
        }
    )
    return name, r.json()["report_id"]

def poll_until_done(report_id, interval=20, timeout=900):
    elapsed = 0
    while elapsed < timeout:
        r = requests.get(
            "https://api.wokelo.ai/api/assets/get_notebook_status/",
            headers=HEADERS,
            params={"report_id": report_id}
        )
        status = r.json().get("status")
        if status == "Completed":
            return True
        if status == "Failed":
            return False
        time.sleep(interval)
        elapsed += interval
    return False

def fetch_report(report_id):
    r = requests.post(
        "https://api.wokelo.ai/api/assets/download_report/",
        headers=HEADERS,
        json={"report_id": report_id, "file_type": "json"}
    )
    return r.json()

# Submit all
with concurrent.futures.ThreadPoolExecutor(max_workers=3) as pool:
    futures = {pool.submit(submit_comparison, name, urls): name for name, urls in COMPARISONS.items()}
    jobs = {}
    for f in concurrent.futures.as_completed(futures):
        name, report_id = f.result()
        jobs[name] = report_id
        print(f"Submitted: {name} → report_id {report_id}")

# Collect
reports = {}
for name, report_id in jobs.items():
    ok = poll_until_done(report_id)
    if ok:
        reports[name] = fetch_report(report_id)
        print(f"Collected: {name}")
    else:
        print(f"Failed: {name}")

print(f"\nCollected {len(reports)} / {len(COMPARISONS)} comparisons")
```

### Exporting a PPT for an IC deck

```python theme={"system"}
import requests

HEADERS = {"Authorization": "Bearer "}

ppt_r = requests.post(
    "https://api.wokelo.ai/api/assets/download_report/",
    headers=HEADERS,
    json={"report_id": 1002345, "file_type": "ppt"}
)

with open("payments_peer_comparison.pptx", "wb") as f:
    f.write(ppt_r.content)

print("Saved payments_peer_comparison.pptx")
```

***

## 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`, missing or empty `websites`, fewer than 2 or more than 5 websites, wrong `workflow` value, or malformed URLs. 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 endpoint. Contact [support@wokelo.ai](mailto: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](mailto:support@wokelo.ai). |

**Handling a `"Failed"` report status:**

```python theme={"system"}
status_r = requests.get(
    "https://api.wokelo.ai/api/assets/get_notebook_status/",
    headers=HEADERS,
    params={"report_id": report_id}
)
if status_r.json().get("status") == "Failed":
    print(f"Report {report_id} failed. Resubmitting...")
    resubmit = requests.post(
        "https://api.wokelo.ai/api/workflow_manager/start/",
        headers=HEADERS,
        json={
            "workflow":  "player_comparison",
            "websites":  ["stripe.com", "paypal.com", "square.com"],
            "workbook_name": "Payments Comparison (retry)"
        }
    )
    new_id = resubmit.json()["report_id"]
    print(f"New report_id: {new_id}")
```

**Retry with exponential back-off:**

```python theme={"system"}
import time, requests

def submit_with_retry(body, api_key, max_retries=3):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    for attempt in range(max_retries):
        try:
            r = requests.post(
                "https://api.wokelo.ai/api/workflow_manager/start/",
                headers=headers,
                json=body,
                timeout=30
            )
            if r.status_code == 429:
                time.sleep(2 ** attempt)
                continue
            r.raise_for_status()
            return r.json()["report_id"]
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
    raise Exception(f"Submission failed after {max_retries} attempts")
```

***

## 8. Best Practices

**`workflow` must always be `"player_comparison"` — distinct from all other Workflow APIs**

The `/api/workflow_manager/start/` endpoint is shared across Company Research (`"company_primer"`), Industry Research (`"industry_primer"`), Peer Comparison (`"player_comparison"`), and Custom Workflow. For Peer Comparison, the value must be exactly `"player_comparison"`. Using any other value will produce the wrong report type or a `400` error.

**Use website URLs, not permalinks**

Peer Comparison identifies companies by website URL, not by Wokelo/Crunchbase permalink. Both bare domain (`"stripe.com"`) and full URL (`"https://www.stripe.com"`) formats are accepted. If Wokelo cannot resolve a URL to a known company, that company may be omitted or have incomplete data in the report. If resolution fails, try the company's canonical homepage URL:

```python theme={"system"}
# ❌ Not accepted by this API
"websites": ["salesforce", "hubspot"]         # Permalinks, not URLs

# ✅ Accepted — bare domain
"websites": ["salesforce.com", "hubspot.com"]

# ✅ Also accepted — full URL
"websites": ["https://www.salesforce.com", "https://www.hubspot.com"]
```

**Pass 2–5 companies — the API does not accept fewer or more**

The `websites` array must contain between 2 and 5 entries. Passing a single URL (not a comparison), an empty array, or more than 5 will return a `400 Bad Request`.

**Store `report_id` immediately**

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:

```python theme={"system"}
report_id = response.json()["report_id"]
save_to_db({"comparison_name": workbook_name, "report_id": report_id, "submitted_at": datetime.now()})
```

**Use 20-second polling intervals — comparisons take longer than single-company reports**

A 5-company comparison runs more research jobs in parallel than Company Research and typically takes 3–7 minutes. Poll every 20 seconds rather than every 15 to avoid unnecessary rate limit consumption:

```python theme={"system"}
for wait in [20, 20, 30, 30, 60, 60, 120]:
    time.sleep(wait)
    status = get_status(report_id)
    if status in ("Completed", "Failed"):
        break
```

**Guard `financials["v"]` against `null` — private companies have sparse financial data**

The `financials` object is populated from S\&P CapIQ and is comprehensive for public companies. For private companies, most or all financial metrics will have `"v": null`. Always check before performing arithmetic:

```python theme={"system"}
# ❌ TypeError when v is null
revenue_m = company["details"]["financials"]["Total revenue"]["v"] / 1e6

# ✅ Safe
fin = company["details"].get("financials", {})
revenue_raw = fin.get("Total revenue", {}).get("v")
revenue_m = revenue_raw / 1e6 if revenue_raw is not None else None
```

**`EBITDA margin (%)` and `Net margin (%)` are fractions, not percentages**

These fields store values like `0.0675` (= 6.75%), not `6.75`. Multiply by 100 before displaying. This is easy to miss when company\_type is "public" and you're cross-checking against other financial sources.

**Use `company_result_mapping` for programmatic matrix generation**

The `key_product_features` section includes a `company_result_mapping` dict keyed by permalink with `"yes"` / `"no"` values. This is the most ergonomic field for building comparison tables programmatically, as you can look up any company's result by permalink without iterating the `company_names` array:

```python theme={"system"}
for row in key_product_features["rows"]:
    ramp_result = row["company_result_mapping"].get("ramp-financial", "unknown")
```

**Use `workbook_name` to differentiate runs — especially in batch workflows**

When running multiple concurrent comparisons, a descriptive `workbook_name` makes it easier to match `report_id` values to their intended use later. Include the date, the landscape name, and any versioning:

```python theme={"system"}
workbook_name = f"Payments Competitive Landscape — {datetime.today().strftime('%Y-%m-%d')}"
```

***

## 9. Related APIs

> **[Company Research](/company-research-doc)**
>
> Generate a single-company deep-dive report — same async workflow pattern, but one company covered in much greater depth.

> **[Industry Research](/industry-research-doc)**
>
> Generate a sector-level intelligence report — covers market sizing, trends, and transaction activity across an entire industry.

> **[Company Instant Enrichment](/company-instant-enrichment-doc)**
>
> Synchronous firmographic enrichment for a single company — instant, no polling, useful for lightweight data needs.

> **[Company News Monitoring](/company-news-monitoring-doc)**
>
> Fetch real-time news for any company — use alongside a Peer Comparison report to layer in the latest competitive developments.

> **[Target Screening](/target-screening-doc)**
>
> Identify and score acquisition targets across a market — use before Peer Comparison to narrow down which companies to benchmark.

> **[Supporting APIs](/supporting-apis-doc)**
>
> Report Status, Download Report, and File Upload — all used alongside Peer Comparison in the async workflow.


# Request Cancel
Source: https://docs.wokelo.ai/request-cancel

POST /api/enterprise/request/cancel/  
Cancels a request already submitted. Pass the unique `request_id` to cancel a pending or in-progress async request.

## Overview

Cancels a request already submitted.

## Endpoint Details

* **Method:** POST
* **Endpoint:** `/api/enterprise/request/cancel/`

## Authentication requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

### Request Parameters

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

#### Query Parameters

**request\_id** `string` *required*

The unique identifier of request which needs to be cancelled

## Response


# Request Result
Source: https://docs.wokelo.ai/request-result

GET /api/enterprise/request/result/
Retrieves the final JSON result of a COMPLETED async request.

## Overview

Retrieves the result of a previously submitted API request.

## Endpoint Details

* **Method:** GET
* **Endpoint:** `/api/enterprise/request/result/`

## Authentication requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

### Request Parameters

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

#### Query Parameters

**request\_id** `string` *required*

The unique identifier of the async request whose status is being checked. Example: `11db67b6-8345-4837-950f-87bbd8d7dcbe`

## Response

#### Successful Response Fields

**request\_id** `string`

Request ID of the initiated request

**status** `string`

Status of the request

**result** `array`

Result depending on the request

```json 200 theme={"system"}
{
    "request_id": "d7a78d10-663a-493f-9b79-be1e6094f3bb",
    "status": "COMPLETED",
    "result": {
        "tesla-motors": {
            "firmographics": {
                "name": "Tesla",
                "website": "https://www.tesla.com",
                "location": "Austin, United States",
                "founded": 2003,
                "type": "public",
                "operating_status": "IPO",
                "ticker": "NASDAQ:TSLA"
            }
        }
    }
}
```


# Request Status
Source: https://docs.wokelo.ai/request-status

GET /api/enterprise/request/status/
Retrieves the current status of a previously submitted async API request.

## Overview

Retrieves the current status of a previously submitted API request.

## Endpoint Details

* **Method:** GET
* **Endpoint:** `/api/enterprise/request/status/`

## Authentication requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

### Request Parameters

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

#### URL Parameters

**request\_id** `string` *required*

The unique identifier of the request whose status is being checked. Example: `11db67b6-8345-4837-950f-87bbd8d7dcbe`

## Response

Successful response will include the `request_id`, `status`, `request_type`, `created_at` and `updated_at` fields.

**Sample Response**

```json theme={"system"}
{
    "request_id": "11db67b6-8345-4837-950f-87bbd8d7dcbe",
    "status": "COMPLETED",
    "request_type": "market_map",
    "created_at": "2026-03-24T18:12:17.787415Z",
    "updated_at": "2026-03-24T18:29:31.041441Z"
}
```

**Possible Status values**

| Status | Description |
| - | - |
| `PENDING` | The request has been received and is queued for processing. |
| `PROCESSING` | The request is currently being processed. |
| `COMPLETED` | The request has finished successfully. Result data is included in the response. |
| `FAILED` | The request encountered an error during processing. |

```json 200 theme={"system"}
{
    "request_id": "b1f10ebf-a251-4e2d-b867-8482ac701987",
    "status": "COMPLETED",
    "request_type": "target_screening",
    "created_at": "2026-03-25T07:24:40.333168Z",
    "updated_at": "2026-03-25T07:30:41.503082Z"
}
```


# Salesforce
Source: https://docs.wokelo.ai/salesforce



## Overview

Wokelo integrates with Salesforce to auto-generate research and enrich your pipeline in a secure, compliant way. By connecting deal intelligence with your existing Sales Cloud workflows, we eliminate manual research and embed updated, context-aware insights directly into your Account and Opportunity records—empowering your team to evaluate opportunities faster than before.

## Key Capabilities & Workflows

### Secure by Design

Wokelo operates on a restricted access model, connecting only to the specific objects and fields you explicitly authorize. Your sensitive pipelines, private notes, and contact data remain completely isolated from the integration.

### Automated Research Triggers

Wokelo connects to Salesforce using Record-Triggered Flows and Platform Events, allowing you to automate research at the moments that matter most:

* **Opportunity Stage Changes** — Automatically generate research workflows when deals advance to Due Diligence or Qualification stages
* **New Account Creation** — Trigger company profiles and competitive intelligence reports when prospects enter your pipeline
* **Bespoke Workflow Execution** — We execute your custom research workflows and write structured outputs back into Salesforce.

### Insights Delivered to Lightning Record Pages

Wokelo research surfaces directly within your Salesforce Activity Timeline and custom fields, giving deal teams instant access to:

* **Company Overviews** — Business model, products, key executives, and founding story
* **Funding Intelligence** — Investment history, cap table insights, and investor details
* **News & Signals** — Real-time coverage of management changes, product launches, and strategic moves

All insights are citation-backed and fully traceable, with references to 200+ sources per report.

## Use Cases

* **New Account added:** When a new company is added to your Salesforce CRM, Wokelo automatically kicks off the right research workflow for that Account. There's no need for your team to manually request, track, or manage research reports—everything starts running in the background as soon as the company appears.
* **Stage change:** When an Opportunity moves from one stage to another (for example, from Qualification to Due Diligence), Wokelo detects the change and automatically runs the relevant research for that stage. This ensures your team always has the right level of insight at the right point in the deal cycle.
* **Insights enrichment:** Wokelo can also push key insights from its reports directly back into Salesforce. These insights can be written into custom fields, the Activity Timeline, or Notes—so your CRM stays continuously enriched with up-to-date, decision-ready intelligence.

![Image](https://mintcdn.com/wokeloai-7cd44985/-6tBwLNmMn5fo79P/images/image-19.png?fit=max\&auto=format\&n=-6tBwLNmMn5fo79P\&q=85\&s=ddbbdc94428192f4cb9792a8c6637456)

![Image](https://mintcdn.com/wokeloai-7cd44985/-6tBwLNmMn5fo79P/images/image-20.png?fit=max\&auto=format\&n=-6tBwLNmMn5fo79P\&q=85\&s=93ab87ab572a392a58549f91e22b22ab)

![Image](https://mintcdn.com/wokeloai-7cd44985/-6tBwLNmMn5fo79P/images/image-21.png?fit=max\&auto=format\&n=-6tBwLNmMn5fo79P\&q=85\&s=31d9b07f4b8b3ffa38e12f6745d5fd3a)

## Get Started

Ready to automate your research and enrich Salesforce with decision-ready insights? Click below and our team will reach out to help set up your integration.

[Integrate Salesforce →](/contact)


# Slack
Source: https://docs.wokelo.ai/slack



*coming soon!*


# Supporting APIs
Source: https://docs.wokelo.ai/supporting-apis-doc



## Company Search

Search the Wokelo database by company name, website or ticker symbol to retrieve permalinks and key attributes needed for other API calls.

> [!NOTE]
>
> If you cannot find a company in the Wokelo database using this API, you can still use our APIs (except the Monitoring API) by passing the complete URL of the company's website instead of its permalink.

`GET   /api/enterprise/company/search`

This is a synchronous API. Results are returned in the HTTP response itself.

```bash cURL wrap theme={"system"}
curl --location 'https://api.wokelo.ai/api/enterprise/company/search?query=wokelo&search_by=name&company_type=all' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json'
```

```python Python wrap theme={"system"}
import requests

url = "https://api.wokelo.ai/api/enterprise/company/search"
params = {"query": "wokelo", "search_by": "name", "company_type": "all"}
headers = {
    "Authorization": "Bearer ",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers, params=params)
print(response.text)
```

Example response:

```json theme={"system"}
{
  "status": "success",
  "data": [
    {
      "name": "Wokelo AI",
      "permalink": "wokelo-ai",
      "short_description": "Wokelo builds purpose-built AI agents...",
      "founded_year": "2023",
      "ipo_status": "private",
      "hq": "Seattle, United States",
      "website": "https://www.wokelo.ai/",
      "ticker": "",
      "country_code": "US",
      "last_funding_round": "Seed"
    }
  ],
  "count": 1
}
```

## Add Company

Add a company to the Wokelo database when it cannot be found using the [Company Search](#company-search) API. Once added, the company becomes available across other Wokelo APIs.

`POST   /api/enterprise/company/add/`

This is an asynchronous API. It returns a `report_id`, which you can track using the [Report status](#report-status) endpoint. Learn more about [How Async APIs work](/how-async-apis-work).

### Authentication

Uses the same authentication and headers as the Company Search API: a Bearer token in the `Authorization` header and `Content-Type: application/json`.

### Request body

| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| `company_name` | string | Yes | Name of the company to add. |
| `website` | string | Yes | Full URL of the company's website. |
| `product_category` | string | No | Product or industry category of the company. |
| `company_type` | string | No | Type of the company. Accepted values: `Public`, `Private`. |

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/enterprise/company/add/' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "company_name": "Aditi Solar",
    "website": "https://aditisolar.in/"
}'
```

```python Python theme={"system"}
import requests

url = "https://api.wokelo.ai/api/enterprise/company/add/"

headers = {
    "Authorization": "Bearer ",
    "Content-Type": "application/json"
}

payload = {
    "company_name": "Aditi Solar",
    "website": "https://aditisolar.in/",
    "product_category": "Solar Energy",
    "company_type": "Private"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

### After the company is added

Track the request with the returned `report_id` using the [Report status](#report-status) endpoint. Once it completes, search for the company with [Company Search](#company-search) to get its `permalink`, and use that permalink as the company reference in other Wokelo API calls.

## File upload

Upload your proprietary files to Wokelo to supplement research reports with internal data. Each uploaded file receives a unique identifier (`fileName`) that you reference in the `custom_files` parameter when creating reports.

`POST   /api/assets/upload/`

```bash cURL wrap theme={"system"}
curl --location 'https://api.wokelo.ai/api/assets/upload/' \
--header 'Authorization: Bearer ' \
--form 'files=@"/path/to/diligence.pdf"' \
--form 'files=@"/path/to/financials.pdf"' \
--form 'fileUUID="[\"k3m8n5p1q6\", \"a7f4b9e2c3\"]"'
```

```python Python wrap theme={"system"}
import requests

url = "https://api.wokelo.ai/api/assets/upload/"

payload = {'fileUUID': '["k3m8n5p1q6", "a7f4b9e2c3"]'}
files = [
    ('files', ('diligence.pdf', open('/path/to/diligence.pdf', 'rb'), 'application/pdf')),
    ('files', ('financials.pdf', open('/path/to/financials.pdf', 'rb'), 'application/pdf'))
]
headers = {'Authorization': 'Bearer '}

response = requests.post(url, headers=headers, data=payload, files=files)
print(response.text)
```

## Report lifecycle

Discovery and Workflow Automation APIs are asynchronous and return a `report_id`. Use these endpoints to track and export the report. See [How Async APIs work](/how-async-apis-work).

### Report status

Get the status of a report that was started using any Wokelo workflow API.

`GET   /api/assets/get_notebook_status/`

| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| `report_id` | integer | Yes | The `report_id` returned when the report was started. |

```bash cURL wrap theme={"system"}
curl --location 'https://api.wokelo.ai/api/assets/get_notebook_status/?report_id=109196' \
--header 'Authorization: Bearer '
```

```python Python wrap theme={"system"}
import requests

url = "https://api.wokelo.ai/api/assets/get_notebook_status/"
headers = {'Authorization': 'Bearer '}

response = requests.get(url, headers=headers, params={"report_id": 109196})
print(response.text)
```

Example response:

```json theme={"system"}
{
  "report_id": 109196,
  "status": "Processing",
  "title": "warehouse automation"
}
```

**List of possible statuses**

| **Status** | **Description** |
| :- | :- |
| `Queued` | The report has been received and is waiting to be processed. |
| `Processing` | The report is actively being generated. |
| `Delayed` | The report is taking longer than expected. |
| `Completed` | Generation finished successfully. The report is ready to download. |
| `Exported` | The report has been exported. |
| `No Data Found` | No data was found for the request. |

### Download report

Download a report once it has completed.

`POST   /api/assets/download_report/`

| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| `report_id` | integer | Yes | Id of the report to export. |
| `file_type` | string | Yes | Export format: `"pdf"`, `"docx"`, `"ppt"` or `"json"`. `ppt` is supported only for Company Research and Industry Research reports. |

```bash cURL wrap theme={"system"}
curl --location 'https://api.wokelo.ai/api/assets/download_report/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data '{
    "report_id": 109196,
    "file_type": "json"
}'
```

```python Python wrap theme={"system"}
import requests

url = "https://api.wokelo.ai/api/assets/download_report/"
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer '
}

response = requests.post(url, headers=headers, json={"report_id": 109196, "file_type": "json"})
print(response.text)
```

### Report config

Retrieve the settings originally used to trigger a report. View the detailed [API reference](/notebook-configuration).

`POST   /api/wkl/notebook/configuration/`

```bash cURL wrap theme={"system"}
curl --location 'https://api.wokelo.ai/api/wkl/notebook/configuration/' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "notebook_id": 103737
}'
```

```python Python wrap theme={"system"}
import requests

url = "https://api.wokelo.ai/api/wkl/notebook/configuration/"
headers = {
    'Authorization': 'Bearer ',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, json={"notebook_id": 103737})
print(response.text)
```

## Credits

APIs to check your current credit balance and review historical credit consumption.

### Credit balance

Retrieve your account's current credit balance, total allotted credits and account expiry period.

`GET   /api/wkl/credits/get-credits-balance/`

```bash cURL wrap theme={"system"}
curl --location 'https://api.wokelo.ai/api/wkl/credits/get-credits-balance/' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json'
```

```python Python wrap theme={"system"}
import requests

url = "https://api.wokelo.ai/api/wkl/credits/get-credits-balance/"
headers = {
    'Authorization': 'Bearer ',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.text)
```

Example response:

```json theme={"system"}
{
  "credits_consumed": 0,
  "acount_expiry_period": "2099-10-04T09:11:05Z",
  "credits_balance": 849.2029999999613,
  "total_credits": 25000.0
}
```

| **Field** | **Type** | **Description** |
| - | - | - |
| `credits_balance` | number | Credits remaining on the account. |
| `total_credits` | number | Total credits allotted to the account. |
| `acount_expiry_period` | string | Expiry timestamp (ISO 8601) for the current credit allotment or plan. |

### Credit logs

Retrieve a paginated log of credit-consuming activity across the account, including reports, newsletters, API calls and assistant usage.

`GET   /api/wkl/credits/get-credits-logs/`

**Query parameters**

| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| `page` | integer | No | Page number to retrieve. Defaults to `1`. |
| `page_size` | integer | No | Number of log entries per page. |

```bash cURL wrap theme={"system"}
curl --location 'https://api.wokelo.ai/api/wkl/credits/get-credits-logs/?page=1&page_size=30' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json'
```

```python Python wrap theme={"system"}
import requests

url = "https://api.wokelo.ai/api/wkl/credits/get-credits-logs/"
headers = {
    'Authorization': 'Bearer ',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers, params={"page": 1, "page_size": 30})
print(response.text)
```

Example response:

```json theme={"system"}
{
  "count": 2604,
  "current_page": 1,
  "total_pages": 87,
  "data": [
    {
      "id": 2681,
      "email": "system@wokelo.ai",
      "date": "2026-07-21T11:05:15.040079+00:00",
      "name": "Newsletter Pipeline",
      "type": "Report",
      "sub_info": "Newsfeed",
      "credit_consumed": 10.0
    },
    {
      "id": 2670,
      "email": "user@example.com",
      "date": "2026-07-17T14:04:16.175945+00:00",
      "name": "Arbor Memorial Inc. - Add Company",
      "type": "API",
      "sub_info": "Add Company",
      "credit_consumed": 0.0
    },
    {
      "id": 2663,
      "email": "user@example.com",
      "date": "2026-07-16T15:29:37.451531+00:00",
      "name": "Acquisition Target Companies",
      "type": "Assistant",
      "sub_info": "generated via deep_research, final summary layer cost",
      "credit_consumed": 10.0
    }
  ],
  "credits_consumed": 0
}
```

**Response fields**

| **Field** | **Type** | **Description** |
| - | - | - |
| `count` | integer | Total number of log entries across all pages. |
| `current_page` | integer | The page number returned in this response. |
| `total_pages` | integer | Total number of pages available. |
| `data` | array | List of individual credit log entries (see below). |
| `credits_consumed` | number | Credits consumed by this logging call itself (typically `0`). |

**Log entry fields**

| **Field** | **Type** | **Description** |
| - | - | - |
| `id` | integer | Unique identifier for the log entry. |
| `email` | string | Email of the user who triggered the activity. May be blank for system-generated entries such as scheduled newsletters. |
| `date` | string | Timestamp (ISO 8601) of the activity. |
| `name` | string | Name of the report, notebook or task associated with the activity. |
| `type` | string | Category of activity. Observed values include `Report`, `Newsletter`, `API` and `Assistant`. |
| `sub_info` | string | Additional context on the specific action taken (e.g. `Add Company`, `Research Plan Validation`, `Newsfeed`). |
| `credit_consumed` | number | Credits consumed by this specific activity. |


# Target Screening
Source: https://docs.wokelo.ai/target-screening

POST https://api.wokelo.ai/api/workflow_manager/start/

## Overview

The Target Screening API generates a long list of potential acquisition targets for a given acquirer, enriched with structured data. You can refine the output with a detailed query, sample companies, geography, company type, employee count, funding stage, financial filters, and more.

Target Screening runs as a workflow. Set `workflow` to `target_screening_v2` in the request body to start one. The request returns a `report_id`, which you then use to track completion and export the results.

## Endpoint Details

* Method: POST
* Endpoint: `/api/workflow_manager/start/`

## Authentication Requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the `/auth/token/` endpoint first.

## Request

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

### Body Parameters

**topic** `string` *required*

The sector or theme in which to screen for targets (e.g. `"Enterprise Software Solutions"`)

**workflow** `string` *required*

The workflow to run. Must be `"target_screening_v2"` for Target Screening.

**workbook\_name** `string` *required*

Name of the workbook that will hold the generated target list (e.g. `"Enterprise Software Solutions"`)

**advanced\_settings** `object` *required*

Acquirer and filter parameters object. Include the object in every request, and send empty values (`""`, `[]`) for any filter you do not want to apply.

**acquirer** `string` *required*

Permalink of the acquiring company or its complete URL (e.g. `"microsoft"` OR `"https://www.microsoft.com/"`)

**detailed\_query** `string`

A descriptive query to refine the target search scope

**companies** `string[]`

Permalinks of representative companies or their complete URLs to anchor the target search.

**geography** `string[]`

Geographic scope. Pass `["Worldwide"]` for no geographic restriction, or a list of ISO country codes (e.g. `["USA", "GBR"]`).

**company\_type** `string`

Type of company to include. Accepted values: `"private"`, `"public"`, `"all"`

**employee\_count** `string[]`

Filter by employee headcount range. Pass an empty array to include all headcounts.

Supported array values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+`

**founded\_year** `object`

Filter by company founding year.

**from** `integer`

Minimum founding year (inclusive), e.g. `2010`

**to** `integer`

Maximum founding year (inclusive), e.g. `2020`

**funding\_stage** `string[]`

Filter by funding stage. Pass an empty array to include all stages.

Supported array values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A`, `Series B`, `Series C`, `Series D`, `Series E`, `Series F`, `Series G`, `Series H`, `Series I`, `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others`

**total\_funding** `object`

Filter by total funding amount raised (in USD).

**from** `number`

Minimum total funding in USD, e.g. `1000000`

**to** `number`

Maximum total funding in USD, e.g. `50000000`

**total\_funding\_include\_blanks** `boolean`

When `true`, companies with no reported total funding are included in the results alongside companies that match the `total_funding` range.

**revenue** `object`

Filter by annual revenue (in USD).

**from** `number`

Minimum annual revenue in USD, e.g. `500000`

**to** `number`

Maximum annual revenue in USD, e.g. `10000000`

```json Basic request theme={"system"}
{
  "topic": "Enterprise Software Solutions",
  "workflow": "target_screening_v2",
  "workbook_name": "Enterprise Software Solutions",
  "advanced_settings": {
    "acquirer": "microsoft",
    "detailed_query": "Enterprise Software Solutions",
    "companies": [],
    "company_type": "all",
    "geography": ["Worldwide"],
    "employee_count": [],
    "funding_stage": [],
    "total_funding_include_blanks": true
  }
}
```

```json Request with filters theme={"system"}
{
  "topic": "Enterprise Software Solutions",
  "workflow": "target_screening_v2",
  "workbook_name": "Enterprise Software Solutions",
  "advanced_settings": {
    "acquirer": "microsoft",
    "detailed_query": "Cloud-based enterprise software platforms for large organizations",
    "companies": [],
    "company_type": "private",
    "geography": ["USA", "GBR"],
    "employee_count": ["51-100", "101-250"],
    "funding_stage": ["Series A", "Series B"],
    "total_funding": {
      "from": 1000000,
      "to": 50000000
    },
    "total_funding_include_blanks": false
  }
}
```

### Response

A successful response returns a `report_id` that identifies the target screening report.

#### Successful Response Fields

**report\_id** `integer`

Unique identifier for the report created by this request. Use it to track completion and to download the results (see below).

```json 200 theme={"system"}
{
  "report_id": 117253
}
```

## Tracking Completion and Exporting Results

Target Screening generation is asynchronous. After you receive a `report_id`:

1. Use `/api/assets/get_notebook_status/` to track completion of the report.
2. Once the report is complete, use `/api/assets/download_report/` to export the results.


# Target Screening
Source: https://docs.wokelo.ai/target-screening-doc

Identify and score potential acquisition targets for a defined acquirer.

## 1. Overview

The Target Screening API identifies and scores potential acquisition targets for a defined acquirer. Given an acquirer and strategic criteria, the AI pipeline evaluates each candidate against the acquirer's profile, M\&A history and stated thesis, and returns a ranked list with deal scores and synergy commentary.

This is an **asynchronous API**. Starting the workflow returns a `report_id`, which you use to track completion and export the results. See [How Async APIs work](/how-async-apis-work).

Each target is scored (1 to 10) on `Overall Score`, `Query Relevance Score`, `Deal Feasibility Score`, `Deal Precedent Score` and `Synergy Potential Score`, each with a written rationale, plus a `Commentary` summarising the deal thesis.

**Common use cases:**

* **Corporate development**: build a scored target pipeline for a strategic acquirer
* **Private equity**: identify bolt-on acquisitions for portfolio companies
* **Buy-side advisory**: build a target universe for a client mandate

***

## 2. Quick Start

**Step 1: Start the workflow**

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "Enterprise Software Solutions",
    "workflow": "target_screening_v2",
    "workbook_name": "Enterprise Software Solutions",
    "advanced_settings": {
      "acquirer": "microsoft",
      "detailed_query": "Enterprise Software Solutions",
      "companies": [],
      "company_type": "all",
      "geography": ["Worldwide"],
      "employee_count": [],
      "funding_stage": [],
      "total_funding_include_blanks": true
    }
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "topic": "Enterprise Software Solutions",
        "workflow": "target_screening_v2",
        "workbook_name": "Enterprise Software Solutions",
        "advanced_settings": {
            "acquirer": "microsoft",
            "detailed_query": "Enterprise Software Solutions",
            "companies": [],
            "company_type": "all",
            "geography": ["Worldwide"],
            "employee_count": [],
            "funding_stage": [],
            "total_funding_include_blanks": True
        }
    }
)
print(response.json()["report_id"])
```

The response contains a `report_id`.

**Step 2: Track completion**

Use `/api/assets/get_notebook_status/` with the `report_id` to check whether the report has completed.

**Step 3: Export results**

Once the report is complete, use `/api/assets/download_report/` with the `report_id` to export the results.

***

## 3. Authentication

Include a Bearer token in the `Authorization` header of every request.

```text theme={"system"}
Authorization: Bearer 
```

Obtain a token from the `/auth/token/` endpoint using the client id and client secret under **Account Details → API Credentials** in the Wokelo dashboard. Contact [support@wokelo.ai](mailto:support@wokelo.ai) if you do not yet have API access.

> [!WARNING]
>
> Never expose your token in client-side code or public repositories.

***

## 4. Request Reference

**Endpoint**

```text theme={"system"}
POST https://api.wokelo.ai/api/workflow_manager/start/
```

The request body is JSON. Include `advanced_settings` in every request and send empty values (`""`, `[]`) for filters you do not want to apply.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `topic` | string | **Required** | The sector or theme to screen for targets (e.g. `"Enterprise Software Solutions"`). |
| `workflow` | string | **Required** | Must be `"target_screening_v2"`. |
| `workbook_name` | string | **Required** | Name of the workbook that holds the generated report. |
| `advanced_settings` | object | **Required** | Acquirer and filter parameters. All fields below live inside this object. |
| `advanced_settings.acquirer` | string | **Required** | Permalink or full URL of the acquiring company (e.g. `"microsoft"`). |
| `advanced_settings.detailed_query` | string | Optional | A descriptive query that refines the target search scope. |
| `advanced_settings.companies` | string\[] | Optional | Permalinks or full URLs of representative companies to anchor the target search. |
| `advanced_settings.geography` | string\[] | Optional | `["Worldwide"]` for no restriction, or ISO country codes (e.g. `["USA", "GBR"]`). |
| `advanced_settings.company_type` | string | Optional | `"private"`, `"public"` or `"all"`. |
| `advanced_settings.employee_count` | string\[] | Optional | Headcount bands. Empty array includes all. Values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1001-5000`, `5001-10000`, `10000+`. |
| `advanced_settings.founded_year` | object | Optional | Object with `from` and/or `to` (integer years, inclusive). |
| `advanced_settings.funding_stage` | string\[] | Optional | Empty array includes all. Values: `Non-Equity Assistance`, `Angel round`, `Pre-seed`, `Seed`, `Series A` to `Series J`, `Corporate-Funded`, `Debt-Funded`, `Private equity round`, `Others`. |
| `advanced_settings.total_funding` | object | Optional | Object with `from` and/or `to`, in USD. |
| `advanced_settings.total_funding_include_blanks` | boolean | Optional | When `true`, companies with no reported total funding are included. |
| `advanced_settings.revenue` | object | Optional | Object with `from` and/or `to`, in USD. |

***

## 5. Response

### Workflow start response

```json theme={"system"}
{
  "report_id": 117253
}
```

| Field | Type | Description |
| - | - | - |
| `report_id` | integer | Unique identifier of the report. Use it to track completion and export results. |

### Report output fields

| Field | Description |
| - | - |
| `Permalink`, `Name`, `Website` | Wokelo company identifier, display name and primary domain. |
| `HQ City`, `HQ Country`, `HQ Continent`, `Founded` | Headquarters location and founding year. |
| `Type`, `Operating Status` | Ownership type (`Public` or `Private`) and status (e.g. `Operating`, `Acquired`, `IPO`). |
| `Product Category`, `Core Offering`, `Product Catalog` | Primary product category, AI-generated description of the core business, and key products. |
| `Employees (Crunchbase)`, `Employees (LinkedIn)` | Headcount band and numeric headcount. |
| `Funding Stage`, `Total Funding`, `Last Funding Date`, `Key Investors` | Funding profile. Total funding is in USD. Typically empty for public companies. |
| `Revenue`, `EBITDA`, `Net Income`, `Market Cap`, `Enterprise Value`, `Ticker`, margins and multiples | Financial data in USD, primarily populated for public companies. |
| `Acquisitions`, `Investments` | Past acquisitions (with year) and notable investments. May be empty. |
| `Overall Score`, `Overall Score Rationale` | Composite strategic fit (1 to 10) and a one-sentence rationale. |
| `Query Relevance Score` | How closely the target matches the stated thesis. |
| `Deal Feasibility Score` | Whether the acquirer can financially execute the deal. |
| `Deal Precedent Score` | Alignment with the acquirer's historical M\&A pattern and deal size. |
| `Synergy Potential Score` | Revenue and cost synergy opportunity. |
| `Commentary` | AI-written deal thesis covering rationale, synergies and integration risks. |

Each sub-score has a matching `... Rationale` field with a one-sentence explanation.

***

## 6. Examples

### Filtered target screen

Private enterprise software targets for Microsoft in the USA and UK, 51 to 250 employees, Series A or B, with \$1M to \$50M total funding.

```bash cURL theme={"system"}
curl --location 'https://api.wokelo.ai/api/workflow_manager/start/' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
    "topic": "Enterprise Software Solutions",
    "workflow": "target_screening_v2",
    "workbook_name": "Enterprise Software Solutions",
    "advanced_settings": {
      "acquirer": "microsoft",
      "detailed_query": "Cloud-based enterprise software platforms for large organizations",
      "companies": [],
      "company_type": "private",
      "geography": ["USA", "GBR"],
      "employee_count": ["51-100", "101-250"],
      "funding_stage": ["Series A", "Series B"],
      "total_funding": {
        "from": 1000000,
        "to": 50000000
      },
      "total_funding_include_blanks": false
    }
  }'
```

```python Python theme={"system"}
import requests

response = requests.post(
    "https://api.wokelo.ai/api/workflow_manager/start/",
    headers={
        "Authorization": "Bearer ",
        "Content-Type": "application/json"
    },
    json={
        "topic": "Enterprise Software Solutions",
        "workflow": "target_screening_v2",
        "workbook_name": "Enterprise Software Solutions",
        "advanced_settings": {
            "acquirer": "microsoft",
            "detailed_query": "Cloud-based enterprise software platforms for large organizations",
            "companies": [],
            "company_type": "private",
            "geography": ["USA", "GBR"],
            "employee_count": ["51-100", "101-250"],
            "funding_stage": ["Series A", "Series B"],
            "total_funding": {
                "from": 1000000,
                "to": 50000000
            },
            "total_funding_include_blanks": False
        }
    }
)
print(response.json()["report_id"])
```

***


# Taxonomy
Source: https://docs.wokelo.ai/taxonomy

List of resources used across API documentation

> **[ISO Country Codes](/iso-country-codes)**
>
> List of all the ISO Country Codes.

> **[News Categories](/news-categories)**
>
> List of supporting new categories.

> **[Industry Names](/industry-names)**
>
> List of supporting industry names.

> **[Form Type Filters](/form-type-filters)**
>
> List of all SEC form type filters.


# Upload File
Source: https://docs.wokelo.ai/upload-file

POST /api/assets/upload/
Upload files to Wokelo to supplement research reports with proprietary data. Each uploaded file receives a unique identifier (`fileName`) that can be referenced in the `custom_files` parameter when creating reports.

- **Individual uploads preferred** – for best performance, upload files one at a time.
- **Bulk upload limits** – maximum 10 files per request, 20 MB limit per file.


## Overview

Upload your files to Wokelo to supplement research reports with proprietary data. Each uploaded file receives a unique identifier that you can reference in the `custom_files` parameter when creating reports.

## Endpoint Details

* **Method:** POST
* **Endpoint:** `/api/assets/upload/`

## Authentication requirements

* Include a valid JWT token in your request header
* If you don't have a token yet, you can get one from the /auth/token/ endpoint first.

## Request

### Request Parameters

#### Header Parameters

**Authorization** `string` *required*

JWT token obtained from the Authentication request

#### Body Parameters

**files** `array of files` *required*

Array of files to be uploaded

**fileUUID** `array of uuids`

Your own UUIDs to track files. Must match the length and order of the `files` array. These UUIDs will be returned in the response alongside Wokelo's `fileName` identifiers.

**Recommended Usage:**

* **Individual uploads preferred** - For best performance, upload files individually
* **Bulk upload limits** - When uploading multiple files, the maximum is 10 files per request with a 20MB limit per file.

## Response

Successful response will include the details of files uploaded successfully and those that failed to upload.

### Successful Response Fields

**status** `String`

Overall upload status (success or error)

**success** `Array of Objects`

Array containing information on successfully uploaded files

**success\[].fileName** `String`

Wokelo's unique file identifier—use this in the `custom_files` parameter when creating reports

**originalName** `String`

Original filename as uploaded

**success\[].mimeType** `String`

Detected file type/format

**uuid** `String`

Your provided UUID (if supplied in request)

**fails** `Array of Objects`

Array containing information about failed uploads (empty on success)

**files\[].reason** `String`

Reason for which the file upload failed

```json 200 theme={"system"}
{
    "status": "success",
    "success": [
        {
            "fileName": "file_116e55ec-041d-4c1e-897c-3adef1576a09",
            "originalName": "lemonade.pdf",
            "mimeType": "pdf",
            "uuid": "a7f4b9e2c3"
        },
        {
            "fileName": "file_e30c7d3f-8bed-46b2-ae9c-eebc879323cc",
            "originalName": "lemonade_diligence.pdf",
            "mimeType": "pdf",
            "uuid": "k3m8n5p1q6"
        }
    ],
    "fails": []
}
```


# Zapier
Source: https://docs.wokelo.ai/zapier



## Overview

Wokelo's Zapier integration connects AI-powered research to your existing tools — CRMs, spreadsheets, project management systems, and more. Automate research workflows and eliminate manual data entry across 8,000+ apps.

## Available Actions

### Research Generation

| Action | What It Does | Required Input |
| :- | :- | :- |
| Create Company Research Report | Full company analysis with market & competitive insights | Company website (+ optional industry) |
| Create Industry Research Report | Industry trends, key players, and market dynamics | Industry name |
| Create Market Map | Competitive landscape mapping for an industry | Industry name |
| Create Pre-Meeting Brief | Quick company briefing before a meeting | Company website (+ optional industry) |
| Create News Report | Recent news and developments for a company | Company website (+ optional filters) |
| Create Player Comparison Report | Side-by-side competitive analysis | Company websites |

### Custom Workflows

| Action | What It Does | Required Input |
| :- | :- | :- |
| Create Company Custom Workflows | Run tailored research workflows for a company | Website + Workflow ID |
| Create Industry Custom Workflows | Run specialized industry analysis workflows | Industry topic + Workflow ID |

### Report Management

| Action | What It Does | Required Input |
| :- | :- | :- |
| Download Report (PDF / PPTX / DOCX / JSON) | Retrieve completed reports in your preferred format | Report ID |
| Upload File | Upload files (from Drive, Box, etc.) for use in custom workflows | File URL(s) |
| Get Report Status | Check report generation progress | Report ID |
| Get Notebook Configurations | Retrieve report metadata (tags, workflow type, sections) | Report ID |

### Triggers

| Trigger | What It Does |
| :- | :- |
| Report Completion Update | Instantly notifies your Zap when a report is ready, passing the report ID, URL, title, and user details |

***

## Setting Up a Zap (Universal Steps)

All Wokelo Zaps follow the same four-step pattern:

**Step 1 — Create a Trigger** Log into [zapier.com](http://zapier.com), click **Zap**, then **Trigger**. Choose the app and event that starts your workflow (e.g., "New row in Google Sheets", "New lead in HubSpot").

**Step 2 — Add Wokelo as an Action** Click **Action**, search for **Wokelo AI**, and select it. If it's your first time, authenticate and connect your Wokelo account.

**Step 3 — Configure the Action** Select the specific Wokelo action, then map the required inputs from your trigger data. Press `/` to browse available dynamic fields from your connected tools.

**Step 4 — Use the Output** Every action returns a **Report ID** and **Report URL**. Map these to your tools — save to a CRM field, update a spreadsheet column, or chain into another action (e.g., download the report, then upload to Google Drive).

***

## Example Workflows

**Investment Pipeline** New company added to CRM, then Generate Company Research Report, then Save report URL to deal record, then Notify investment team via Slack

**Pre-Meeting Prep** Meeting scheduled in calendar, then Generate Pre-Meeting Brief, then Attach report link to CRM opportunity, then Email brief to attendees

**Competitive Intelligence** Weekly scheduled trigger, then Generate Market Maps for key industries, then Upload to Google Drive, then Share digest with leadership

**Full Automation Loop** Trigger report creation, then Listen for Report Completion Update, then Download PPTX, then Upload to cloud storage, then Update CRM, then Notify team

***

## Best Practices

* **Validate inputs:** Ensure website URLs include `https://` and industry names are specific (e.g., "B2B SaaS" not just "Software").
* **Use the Report Completion trigger** before downloading — only attempt downloads on completed reports.
* **Chain actions** for end-to-end automation: create → monitor completion → download → distribute.
* **Store Report IDs** in your CRM or spreadsheet for future reference and audit tracking.
* **For file uploads:** maximum 10 files per request, 20MB per file. Use the returned success string as input for custom workflow actions.