> ## Documentation Index > Fetch the complete documentation index at: https://docs.wokelo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Company Deep Intelligence > Generate on-demand AI-synthesised intelligence on one or more companies simultaneously — selectively requesting product portfolios, launch timelines, strategic initiatives, partnerships, business models, key customers, leadership profiles, and employee or product sentiment in a single composable request. ## 1. Overview The Company Deep Intelligence API generates structured, source-cited intelligence on any company or set of companies. Where Company Instant Enrichment returns raw firmographic data, this API returns **AI-synthesised narratives** — product portfolios, strategic moves, launch timelines, key customer profiles, leadership analysis, and employee sentiment — going well beyond what structured databases can provide. This is an **asynchronous POST API** — submitting a request returns a `request_id` (a UUID string) and an initial `"PENDING"` status immediately. You then poll the [Request Status](/supporting-apis-doc#request-status) endpoint until status becomes `"COMPLETED"`, at which point the full result is embedded directly in the status response. **The two-step workflow:** ```text theme={"system"} Step 1: POST /api/enterprise/company/enrich/ → returns request_id + status: "PENDING" Step 2: GET /api/enterprise/request/status/ → poll until status = "COMPLETED"; result embedded in response ``` This API uses the **same async pattern as Industry Deep Intelligence** — `request_id` (UUID string), polls `request/status/`, and embeds the completed result directly in the status response. It does **not** use the Workflow API infrastructure (`report_id`, `get_notebook_status`, `download_report`). The two patterns are not interchangeable. **Two capabilities make this API architecturally distinct from all others in Wokelo:** * **Multi-company in one request** — pass an array of company identifiers (`companies`) to enrich 1–N companies simultaneously. Results are returned as a dict keyed by each company identifier. * **Section-selective output** — choose exactly which of the 9 section types to generate. Request only what you need; each additional section adds processing time. **The nine available sections:** | Section | What you get | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `products_and_services` | Full product portfolio — overview narrative with screenshot, categorised product areas with per-product titles and summaries, and source citations | | `product_launches` | Dated release timeline — recent launches with initiative names, bullet-point summaries, and source URLs; plus future announcements array | | `strategic_initiatives` | Operational moves — office expansions, hiring activity, layoffs, M\&A, awards, and other named strategic areas, each with sourced bullet points | | `partnerships` | Partnership ecosystem — technology partners, channel partners, and strategic alliances with context and sourcing | | `business_model` | Revenue model analysis — pricing strategy, monetisation approach, and go-to-market structure | | `key_customers` | Major customer identification — named accounts with industry context, deal details, and source citations | | `management_profiles` | Leadership team analysis — background, track record, tenure, and career trajectory for key executives | | `employee_sentiment` | Workplace culture analysis — synthesised from employee reviews and Glassdoor data | | `product_sentiment` | Market perception analysis — synthesised from product reviews, G2, Capterra, and social signals | **Common use cases:** * **Pre-IC product intelligence sweep** — for a set of target companies, request `products_and_services` + `product_launches` + `strategic_initiatives` to understand product trajectory and roadmap signals before a committee meeting * **Competitive diligence on multiple players at once** — send 3–5 competitors in a single `companies` array and get parallel product and business model analysis without chaining calls * **Leadership due diligence** — request `management_profiles` for an acquisition target and its key executives to surface background, tenure, and track record data * **Customer and partner mapping** — request `key_customers` + `partnerships` to identify major accounts and technology alliances before outreach or deal structuring * **Employee health monitoring** — request `employee_sentiment` across a portfolio to catch early cultural warning signals or compare workplace satisfaction across peers * **CRM enrichment pipeline** — batch enrich a watchlist of companies on specific sections and push results into Salesforce, HubSpot, or DealCloud records automatically *** ## 2. Quick Start **Step 1 — Submit a request** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/enterprise/company/enrich/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "companies": [ "https://tesla.com" ], "sections": [ "products_and_services", "product_launches" ] }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "companies": ["https://tesla.com"], "sections": ["products_and_services", "product_launches"] } ) data = response.json() request_id = data["request_id"] print(f"Submitted. request_id: {request_id} status: {data['status']}") ``` **Step 2 — Poll until completed and retrieve the result** ```python theme={"system"} import time, requests def poll_until_complete(request_id, api_key, poll_interval=10, timeout=600): headers = {"Authorization": f"Bearer {api_key}"} elapsed = 0 while elapsed < timeout: r = requests.get( "https://api.wokelo.ai/api/enterprise/request/status/", headers=headers, params={"request_id": request_id} ) data = r.json() status = data.get("status", "") print(f"[{elapsed}s] Status: {status}") if status == "COMPLETED": return data["result"] # result is embedded in the status response if status == "FAILED": raise Exception(f"Request {request_id} failed") time.sleep(poll_interval) elapsed += poll_interval raise TimeoutError(f"Request {request_id} did not complete within {timeout}s") result = poll_until_complete(request_id, api_key="") print(f"Companies enriched: {list(result.keys())}") ``` **Step 3 — Work with the result** ```python theme={"system"} # Result is keyed by the company identifier you submitted company_data = result["https://tesla.com"] # or result["tesla"] if you used a permalink firmographics = company_data["firmographics"] print(f"Company: {firmographics['name']}") print(f"Type: {firmographics['type']} | Status: {firmographics['operating_status']}") enrichment = company_data["CP enrichment"] # Products overview if "products_and_services" in enrichment: overview = enrichment["products_and_services"]["product_overview"]["summary"] print(f"\nProducts overview:\n{overview[:400]}...") # Recent launches if "product_launches" in enrichment: launches = enrichment["product_launches"]["product_launches_and_initiatives"]["released_products"] print(f"\nRecent launches ({len(launches)}):") for launch in launches[:3]: print(f" [{launch['date']}] {launch['initiative']}") ``` *** ## 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. 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/enterprise/company/enrich/ ``` All parameters are passed as JSON in the request body. | Parameter | Type | Required | Description | | ----------- | --------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `companies` | string\[] | **Required** | Array of company identifiers. Each entry is either a **permalink** (e.g. `"zendesk"`, `"stripe"`) or a **website URL** (e.g. `"https://tesla.com"`). Permalinks resolve faster — use the [Company Search API](/supporting-apis-doc#company-search) to look them up. Multiple companies are processed in parallel; results are keyed by the identifier you provide. | | `sections` | string\[] | **Required** | Array of one or more section identifiers to include in the output. Request only what you need — each section adds processing time. See the supported sections table in Section 1. | There is no hard-coded limit on the number of companies per request, but processing time scales with the number of companies × sections. For large watchlists, consider batching into groups of 5–10 companies and running requests concurrently. **Full request example:** ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/enterprise/company/enrich/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "companies": [ "zendesk", "freshworks", "intercom" ], "sections": [ "products_and_services", "product_launches", "strategic_initiatives" ] }' ``` ```python Python theme={"system"} import requests response = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={ "companies": ["zendesk", "freshworks", "intercom"], "sections": [ "products_and_services", "product_launches", "strategic_initiatives" ] } ) print(response.json()) # {"request_id": "c2ad9d34-f432-4b9b-b5a2-46fbd124db5f", "status": "PENDING"} ``` *** ## 5. Response ### Submission response The initial POST returns a `202 Accepted` with two fields: ```json theme={"system"} { "request_id": "c2ad9d34-f432-4b9b-b5a2-46fbd124db5f", "status": "PENDING" } ``` | Field | Type | Description | | ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request_id` | string (UUID) | Unique identifier for this request. Use with the [Request Status](/supporting-apis-doc#request-status) endpoint to poll for completion. This is a UUID string — not an integer `report_id`. The two are not interchangeable. | | `status` | string | Initial status, always `"PENDING"` on submission. | ### Status polling response Poll `GET /api/enterprise/request/status/?request_id={request_id}`. Status values: | Status value | Meaning | | -------------- | ----------------------------------------------------------------------------------------- | | `"PENDING"` | Request is queued, waiting to start. | | `"PROCESSING"` | Analysis is in progress. | | `"COMPLETED"` | All sections for all companies are ready. The full `result` is embedded in this response. | | `"FAILED"` | Request failed. Retry the submission. | ### Completed result structure When status is `"COMPLETED"`, the polling response includes a `result` object. The result is a **dict keyed by company identifier** — one entry per company submitted in the `companies` array: ```json theme={"system"} { "request_id": "...", "status": "COMPLETED", "result": { "zendesk": { "firmographics": { ... }, "CP enrichment": { ... }, "meta": { ... } }, "freshworks": { "firmographics": { ... }, "CP enrichment": { ... }, "meta": { ... } } } } ``` **The result key matches the identifier you submitted.** If you sent `"https://tesla.com"`, the result key is `"https://tesla.com"`. If you sent `"tesla"`, the result key is `"tesla"`. Use the same identifier to look up each company's data. ### Per-company object structure Each company object contains three top-level keys: **`firmographics`** A lean identity card for the company. No financials — for financial data use Peer Comparison or Company Research. | Field | Type | Description | | ------------------ | -------------- | ------------------------------------------------------------------ | | `name` | string | Company display name. | | `website` | string | Canonical website URL. | | `location` | string | City and country of headquarters. | | `founded` | integer | Year the company was founded. | | `type` | string | Ownership structure: `"public"`, `"private"`, `"startup"`. | | `operating_status` | string | Current status: `"Operating"`, `"Acquired"`, `"IPO"`, or similar. | | `ticker` | string or null | Stock ticker (e.g. `"NASDAQ:FRSH"`). `null` for private companies. | **`CP enrichment`** A dict containing your requested sections. Each section key maps to a section-specific data structure (see section schemas below). **`meta`** | Field | Type | Description | | -------------- | ------- | --------------------------------------------------------------------------------------- | | `report_id` | integer | Internal Wokelo report identifier for this enrichment run. Different from `request_id`. | | `title` | string | Auto-generated report title (e.g. `"Zendesk - API Insights"`). | | `user` | string | Email address of the user associated with the API token. | | `dt_createdon` | string | Datetime the report was created, in `YYYY-MM-DD HH:MM:SS` format (UTC). | ### Section-level response schemas **`products_and_services`** ```json theme={"system"} { "products_and_services": { "product_overview": { "source": [ { "id": 1, "title": "...", "url": "...", "publisher": "", "date": "" } ], "summary": "", "screenshot_url": "" }, "products_and_services": [ { "product_area": "Customer Service AI Solutions", "details": [ { "title": "AI Agents", "summary": "Autonomous bots that resolve..." } ], "sources": "1-3" } ] } } ``` The `sources` field on each product area item is a **string range** (e.g. `"1-3"`, `"4-6"`) referencing IDs in the `product_overview.source` array — not a standalone citations array. **`product_launches`** ```json theme={"system"} { "product_launches": { "product_launches_and_initiatives": { "released_products": [ { "date": "26-Mar-2025", "initiative": "Resolution Platform", "sources": [ { "url": "...", "title": "...", "publisher": "...", "publishedDate": "2025-03-26" } ], "summary": [ "AI Integration: **AI-powered resolution** platform with autonomous agents.", "Outcome Focus: Designed to deliver **faster resolutions**." ] } ], "future_announcements": [ { "date": "31-Aug-2027", "initiative": "Sell Discontinuation", "sources": [ { ... } ], "summary": [ "Product Exit: Shutting down **Zendesk Sell** on **Aug 31, 2027**." ] } ] } } } ``` `summary` inside each launch is an **array of strings** (bullet points), not a single string. `sources` here is an array of citation objects (not the string-range pattern used in `products_and_services`). **`strategic_initiatives`** ```json theme={"system"} { "strategic_initiatives": { "strategic_moves": [ { "Area": "Layoffs", "Details": [ { "point": "**Freshworks laid off 13% of workforce** (660 employees)...", "sources": [ { "url": "...", "title": "...", "publisher": "...", "publishedDate": "..." } ] } ] }, { "Area": "Office expansion", "Details": [ { "point": "...", "sources": [ ... ] } ] } ] } } ``` `strategic_moves` is an array of area objects. `Area` is a string label (e.g. `"Layoffs"`, `"Hiring"`, `"Office expansion"`, `"Awards and recognitions"`). `Details` is an array of sourced bullet-point objects. The `sources` field schema differs between sections. In `products_and_services` items, `sources` is a string range like `"1-3"`. In `product_launches` and `strategic_initiatives`, `sources` is an array of citation objects with `url`, `title`, `publisher`, and `publishedDate`. Always check the type before iterating. *** ## 6. Examples ### Product intelligence on multiple companies before IC Request product portfolio and launch data for three competitors simultaneously. ```bash cURL theme={"system"} curl --location 'https://api.wokelo.ai/api/enterprise/company/enrich/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "companies": ["zendesk", "freshworks", "intercom"], "sections": ["products_and_services", "product_launches", "strategic_initiatives"] }' ``` ```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/enterprise/company/enrich/", headers=HEADERS, json={ "companies": ["zendesk", "freshworks", "intercom"], "sections": [ "products_and_services", "product_launches", "strategic_initiatives" ] } ) request_id = submit.json()["request_id"] print(f"Submitted. request_id: {request_id}") # Poll while True: r = requests.get( "https://api.wokelo.ai/api/enterprise/request/status/", headers={"Authorization": f"Bearer {API_KEY}"}, params={"request_id": request_id} ) data = r.json() status = data.get("status") print(f"Status: {status}") if status == "COMPLETED": result = data["result"] break if status == "FAILED": raise Exception("Request failed") time.sleep(10) # Process each company for company_key, company_data in result.items(): firm = company_data["firmographics"] enrichment = company_data["CP enrichment"] print(f"\n{'='*60}") print(f"{firm['name']} ({firm['type']} | {firm['operating_status']})") print('='*60) # Product overview if "products_and_services" in enrichment: summary = enrichment["products_and_services"]["product_overview"]["summary"] print(f"\nProducts:\n{summary[:400]}...") # Recent launches if "product_launches" in enrichment: launches = enrichment["product_launches"]["product_launches_and_initiatives"]["released_products"] print(f"\nRecent launches ({len(launches)}):") for launch in launches[:3]: print(f" [{launch['date']}] {launch['initiative']}") for bullet in launch["summary"][:1]: print(f" • {bullet}") ``` **Sample submission response:** ```json theme={"system"} { "request_id": "c2ad9d34-f432-4b9b-b5a2-46fbd124db5f", "status": "PENDING" } ``` ### Strategic initiative monitoring — layoffs and hiring signals Track workforce and strategic moves across a watchlist to surface adverse or growth signals. ```python theme={"system"} import requests, time from collections import defaultdict API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} WATCHLIST = ["zendesk", "freshworks", "salesforce", "hubspot", "pipedrive"] submit = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers=HEADERS, json={ "companies": WATCHLIST, "sections": ["strategic_initiatives"] } ) request_id = submit.json()["request_id"] # Poll while True: r = requests.get( "https://api.wokelo.ai/api/enterprise/request/status/", headers={"Authorization": f"Bearer {API_KEY}"}, params={"request_id": request_id} ) data = r.json() if data["status"] == "COMPLETED": result = data["result"] break if data["status"] == "FAILED": raise Exception("Request failed") time.sleep(10) ADVERSE_AREAS = {"Layoffs", "Workforce Reductions", "Office Closures"} GROWTH_AREAS = {"Hiring", "Office expansion", "Awards and recognitions"} print("=== Adverse Signals ===") for company_key, company_data in result.items(): name = company_data["firmographics"]["name"] moves = company_data["CP enrichment"].get("strategic_initiatives", {}).get("strategic_moves", []) for move in moves: if move["Area"] in ADVERSE_AREAS: print(f"\n[{name}] {move['Area']}") for detail in move["Details"][:2]: print(f" • {detail['point'][:200]}...") print("\n=== Growth Signals ===") for company_key, company_data in result.items(): name = company_data["firmographics"]["name"] moves = company_data["CP enrichment"].get("strategic_initiatives", {}).get("strategic_moves", []) for move in moves: if move["Area"] in GROWTH_AREAS: print(f"\n[{name}] {move['Area']}") for detail in move["Details"][:1]: print(f" • {detail['point'][:200]}...") ``` ### Product launch timeline comparison Extract and compare product launch timelines across a competitive set. ```python theme={"system"} from datetime import datetime submit = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers=HEADERS, json={ "companies": ["zendesk", "freshworks", "intercom"], "sections": ["product_launches"] } ) request_id = submit.json()["request_id"] # Poll (abbreviated — use the poll helper from Quick Start) result = poll_until_complete(request_id, API_KEY) # Flatten all launches into a single timeline all_launches = [] for company_key, company_data in result.items(): name = company_data["firmographics"]["name"] launches = ( company_data["CP enrichment"] .get("product_launches", {}) .get("product_launches_and_initiatives", {}) .get("released_products", []) ) for launch in launches: all_launches.append({ "company": name, "date": launch["date"], "initiative": launch["initiative"], "bullets": launch["summary"] }) # Sort most recent first def parse_date(d): try: return datetime.strptime(d, "%d-%b-%Y") except ValueError: return datetime.min all_launches.sort(key=lambda x: parse_date(x["date"]), reverse=True) print("Unified Product Launch Timeline\n" + "="*60) for launch in all_launches[:20]: print(f"[{launch['date']}] {launch['company']} — {launch['initiative']}") for bullet in launch["bullets"][:1]: print(f" • {bullet}") ``` ### Leadership due diligence Request `management_profiles` for an acquisition target to surface executive backgrounds. ```python theme={"system"} submit = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers=HEADERS, json={ "companies": ["https://www.airbase.com"], "sections": ["management_profiles", "key_customers", "partnerships"] } ) request_id = submit.json()["request_id"] result = poll_until_complete(request_id, API_KEY) company_data = result["https://www.airbase.com"] enrichment = company_data["CP enrichment"] print(f"Target: {company_data['firmographics']['name']}") print(f"Status: {company_data['firmographics']['operating_status']}\n") if "management_profiles" in enrichment: print("=== Leadership ===") # Navigate section-specific structure for key, val in enrichment["management_profiles"].items(): if isinstance(val, dict): print(str(val)[:500]) ``` ### Employee sentiment sweep across a portfolio Monitor workplace health signals across portfolio companies. ```python theme={"system"} submit = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers=HEADERS, json={ "companies": ["salesforce", "hubspot", "zendesk", "freshworks"], "sections": ["employee_sentiment", "product_sentiment"] } ) request_id = submit.json()["request_id"] result = poll_until_complete(request_id, API_KEY) for company_key, company_data in result.items(): name = company_data["firmographics"]["name"] enrichment = company_data["CP enrichment"] print(f"\n{name}") for section in ["employee_sentiment", "product_sentiment"]: if section in enrichment: # Navigate to summary — structure varies; iterate to find it for sub_key, sub_val in enrichment[section].items(): if isinstance(sub_val, dict) and "summary" in sub_val: print(f" [{section}] {sub_val['summary'][:200]}...") ``` ### Batch enrichment across a large watchlist For large watchlists, batch companies into groups and run requests concurrently. ```python theme={"system"} import requests, time, concurrent.futures API_KEY = "" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} WATCHLIST = [ "salesforce", "hubspot", "pipedrive", "zoho", "freshworks", "zendesk", "intercom", "servicenow", "atlassian", "jira-software" ] def submit_batch(companies, sections): r = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers=HEADERS, json={"companies": companies, "sections": sections} ) return r.json()["request_id"] def poll_until_done(request_id, interval=10, timeout=600): elapsed = 0 while elapsed < timeout: r = requests.get( "https://api.wokelo.ai/api/enterprise/request/status/", headers={"Authorization": f"Bearer {API_KEY}"}, params={"request_id": request_id} ) data = r.json() if data["status"] == "COMPLETED": return data["result"] if data["status"] == "FAILED": return None time.sleep(interval) elapsed += interval return None SECTIONS = ["products_and_services", "strategic_initiatives"] BATCH_SIZE = 5 # Split into batches batches = [WATCHLIST[i:i+BATCH_SIZE] for i in range(0, len(WATCHLIST), BATCH_SIZE)] # Submit all batches concurrently with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool: futures = {pool.submit(submit_batch, batch, SECTIONS): batch for batch in batches} jobs = [] for f in concurrent.futures.as_completed(futures): request_id = f.result() jobs.append(request_id) print(f"Submitted batch → {request_id}") # Collect all results all_results = {} for request_id in jobs: result = poll_until_done(request_id) if result: all_results.update(result) print(f"Collected batch from {request_id}: {list(result.keys())}") print(f"\nTotal companies enriched: {len(all_results)}") ``` ### JavaScript / Node.js ```javascript theme={"system"} const fetch = require("node-fetch"); async function enrichCompanies(companies, sections) { // Submit const submitRes = await fetch( "https://api.wokelo.ai/api/enterprise/company/enrich/", { method: "POST", headers: { "Authorization": `Bearer ${process.env.WOKELO_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ companies, sections }) } ); const { request_id } = await submitRes.json(); console.log(`Submitted. request_id: ${request_id}`); // Poll while (true) { await new Promise(r => setTimeout(r, 10000)); const statusRes = await fetch( `https://api.wokelo.ai/api/enterprise/request/status/?request_id=${request_id}`, { headers: { "Authorization": `Bearer ${process.env.WOKELO_API_KEY}` } } ); const data = await statusRes.json(); console.log(`Status: ${data.status}`); if (data.status === "COMPLETED") return data.result; if (data.status === "FAILED") throw new Error(`Request ${request_id} failed`); } } // Example: product intelligence on three CX platforms enrichCompanies( ["zendesk", "freshworks", "intercom"], ["products_and_services", "product_launches"] ).then(result => { for (const [companyKey, data] of Object.entries(result)) { console.log(`\n${data.firmographics.name}`); const launches = data["CP enrichment"] ?.product_launches ?.product_launches_and_initiatives ?.released_products ?? []; console.log(` Recent launches: ${launches.length}`); launches.slice(0, 2).forEach(l => console.log(` [${l.date}] ${l.initiative}`)); } }); ``` *** ## 7. Error Handling The API uses standard HTTP status codes. The submission endpoint returns a `202` on success and synchronous errors for invalid requests. Processing errors appear as `"FAILED"` when polling. | Status | Meaning | Cause & Resolution | | --------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `202 Accepted` | Request accepted | `request_id` and `"PENDING"` status returned. Proceed to polling. | | `400 Bad Request` | Invalid parameters | Missing `companies`, empty `companies` array, invalid `sections` value, or unrecognised company identifier. 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 the requested sections. Contact [support@wokelo.ai](mailto:support@wokelo.ai). | | `429 Too Many Requests` | Rate limit exceeded | Implement exponential back-off. The response includes a `Retry-After` header. | | `500 Internal Server Error` | Server error | Retry after a brief delay. If the issue persists, contact [support@wokelo.ai](mailto:support@wokelo.ai). | **Handling a `"FAILED"` request status:** ```python theme={"system"} r = requests.get( "https://api.wokelo.ai/api/enterprise/request/status/", headers={"Authorization": f"Bearer {API_KEY}"}, params={"request_id": request_id} ) if r.json().get("status") == "FAILED": print(f"Request {request_id} failed. Resubmitting...") resubmit = requests.post( "https://api.wokelo.ai/api/enterprise/company/enrich/", headers=HEADERS, json={"companies": ["zendesk"], "sections": ["products_and_services"]} ) print(f"New request_id: {resubmit.json()['request_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/enterprise/company/enrich/", headers=headers, json=body, timeout=30 ) if r.status_code == 429: time.sleep(2 ** attempt) continue r.raise_for_status() return r.json()["request_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 **Request only the sections you need — each section adds processing time** Unlike Workflow APIs that produce a fixed full report, this API generates only the sections you explicitly request. A focused two-section request (e.g. `products_and_services` + `product_launches`) completes significantly faster than all nine: ```python theme={"system"} # Fast pre-IC check — two sections json={"companies": ["zendesk"], "sections": ["products_and_services", "product_launches"]} # Full intelligence sweep — all nine sections, expect longer processing json={"companies": ["zendesk"], "sections": [ "products_and_services", "product_launches", "strategic_initiatives", "partnerships", "business_model", "key_customers", "management_profiles", "employee_sentiment", "product_sentiment" ]} ``` **Use permalinks over website URLs for faster resolution** Permalinks (e.g. `"zendesk"`, `"stripe"`) resolve faster and more reliably than website URLs, particularly for companies with complex domain structures. Use the [Company Search API](/supporting-apis-doc#company-search) to look up a company's permalink when you only have its name: ```python theme={"system"} search = requests.get( "https://api.wokelo.ai/api/enterprise/company/search", headers=HEADERS, params={"query": "Zendesk", "search_by": "name"} ) permalink = search.json()["data"][0]["permalink"] # "zendesk" ``` **Batch companies into a single request rather than making separate calls** This is the most important efficiency pattern for this API. Sending five companies in one `companies` array is significantly faster than five separate requests, because companies are processed in parallel on Wokelo's infrastructure: ```python theme={"system"} # ❌ Inefficient — five separate round-trips for company in ["zendesk", "freshworks", "intercom", "servicenow", "atlassian"]: submit_request([company], sections) # ✅ Efficient — one request, five companies processed in parallel submit_request(["zendesk", "freshworks", "intercom", "servicenow", "atlassian"], sections) ``` **Result keys match the identifier you submitted — use it consistently** If you submit `"https://tesla.com"`, the result key is `"https://tesla.com"`. If you submit `"tesla"`, the key is `"tesla"`. Mixing identifier formats in the same request (some URLs, some permalinks) produces result keys in the format you used. Be consistent within a request to simplify downstream processing: ```python theme={"system"} # ❌ Mixed formats — inconsistent result keys companies=["https://zendesk.com", "freshworks", "https://intercom.com"] # ✅ Consistent — all permalinks, all result keys are permalinks companies=["zendesk", "freshworks", "intercom"] ``` **`sources` schema differs between sections — check type before iterating** In `products_and_services`, the `sources` field on each product area item is a **string range** (e.g. `"1-3"`) referencing the `product_overview.source` array by ID. In `product_launches` and `strategic_initiatives`, `sources` is an **array of citation objects**. Always check the type before iterating: ```python theme={"system"} sources = product_area.get("sources", "") # products_and_services — string range if isinstance(sources, str): print(f"Source IDs: {sources}") # e.g. "1-3" # product_launches / strategic_initiatives — array of citation objects elif isinstance(sources, list): for cite in sources: print(f" {cite['title']} ({cite['publishedDate']})") ``` **`product_launches.summary` is an array of strings, not a single string** Each launch object's `summary` field is a list of bullet-point strings, not a single narrative string. Iterate it rather than printing directly: ```python theme={"system"} # ❌ TypeError — summary is a list, not a string print(launch["summary"][:200]) # ✅ Correct for bullet in launch["summary"]: print(f" • {bullet}") ``` **`request_id` is a UUID string — use the correct polling endpoint** This API returns `request_id` (UUID string). The Workflow APIs return `report_id` (integer). They use completely different polling endpoints and cannot be swapped: ```python theme={"system"} # ❌ Wrong endpoint for this API requests.get(".../api/assets/get_notebook_status/", params={"report_id": request_id}) # ✅ Correct endpoint for Company Deep Intelligence requests.get(".../api/enterprise/request/status/", params={"request_id": request_id}) ``` **Understand when to use Company Deep Intelligence vs Company Research** Both APIs generate company intelligence, but they serve different needs. Company Deep Intelligence is **section-selective and multi-company** — ideal for focused sweeps across watchlists where you need specific intelligence types quickly, with results returned in the polling response. Company Research always generates a **fixed five-section deep-dive report for one company** through the Workflow infrastructure and supports PDF/DOCX/PPT export. Use Company Deep Intelligence for flexible pipeline enrichment and competitive sweeps; use Company Research when you need a complete formatted deliverable for a single company. *** ## 9. Related APIs The industry-level equivalent — section-selective async intelligence on any sector or market, using the same request\_id pattern. Fixed five-section deep-dive for a single company with PDF/DOCX/PPT export — use when you need a complete formatted deliverable. Synchronous firmographic data — returns raw structured fields instantly. Use for lightweight data needs where AI narratives aren't required. Real-time news for any company — synchronous, no polling. Complements Company Deep Intelligence for current event context. Side-by-side benchmarking of 2–5 companies with financial data, feature matrices, and business model comparison — async Workflow API. Request Status and Company Search — both used alongside Company Deep Intelligence in the async workflow.