> For the complete documentation index, see [llms.txt](https://api.docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.docs.blockbrain.ai/integration-best-practices/sales-opportunities.md). # Sales Opportunities ## 1. Introduction The intended use case is to analyze target companies for market opportunities and generate personalized outreach emails. The opportunity detection logic is configured in the Blockbrain UI and can be accessed via the API for automation purposes. All functionality available in the UI is also exposed through the API. The UI should be used to set up the opportunity detection bots and their prompts, while the API should be used to implement automated or large scale workflows. The complete Blockbrain API documentation is provided here: Before proceeding with the workflow, ensure you have: 1. Configured your Sales Navigator bot. 2. Defined and saved the opportunity detection prompts in the prompt library. 3. Selected the appropriate LLM model in the bot settings (for example GPT-4). 4. Retrieved your **`bot_id`**, **`agentTaskId`** as described in Section 4 of this guide. ## 2. API Basic Workflow The process for analyzing companies and generating opportunities consists of five main steps. It is strongly recommended to create a separate Data Room for each batch of companies to maintain isolation between analyses and enable parallel processing. ### Step 1: Create Data Room This operation creates a new conversation (Data Room) associated with your Sales Navigator bot. • **Endpoint:** POST `/cortex/active-bot/bot_id/convo`\ • **API Reference:** [ Create Data Room – API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-active-bot/operation/add_convo_to_bot_cortex_active_bot__bot_id__convo_post) Example request URL ``` https://blocky.theblockbrain.ai/cortex/active-bot/68514f586cd169f603f38a4e/convo ``` Example request body ```json { "convoName": "New Data Room" } ``` Example response body ```json { "body": { "dataRoomId": "689e2ee5ef2860b689633021" } } ``` The response will contain a `dataRoomId` that identifies this data room. This `dataRoomId` is needed for the following steps. ### Step 2: Enable Web Search This operation enables web research capabilities for the data room. • **Endpoint:** PATCH `/cortex/conversation/dataRoomId`\ • **API Reference:** [Patch Data Room – API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/update_convo_detail_cortex_conversation__convo_id__patch) Example request URL ``` https://blocky.theblockbrain.ai/cortex/conversation/689e2ee5ef2860b689633021 ``` Example request body ```json { "enableWebSearch": true } ``` ### Step 3: Submit Company for Analysis This operation sends the company name with date range to the web research agent. * **Endpoint**: POST /cortex/completions/v2/user-input * **API Reference**: [Add User Messages – API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-completions/operation/add_user_messages_cortex_completions_user_input_post) Example request URL ``` https://blocky.theblockbrain.ai/cortex/completions/v2/user-input ``` Example request body ```json { "content": "COMPANY: Google\n\nFROM DATE: 2025-10-13\n\nTO DATE: 2025-10-20", "actionType": "direct-agent", "messageType": "user-question", "sessionId": "689e2ee5ef2860b689633021", "convoId": "689e2ee5ef2860b689633021", "agentTaskId": "68b7e73788b8c14e131b543d" } ``` If **`enableStreaming`** is enabled, responses are returned token by token using [Streaming](/concepts/streaming.md). In that case, you may concatenate all returned new\_token objects to form the final output. Check the Prompt Template (`agentTaskId`) used for this query at [#news-search](#news-search "mention") ### Step 4: Disable Web Search This operation disables web research capabilities after data collection is complete to conserve resources. • **Endpoint:** PATCH `/cortex/conversation/dataRoomId`\ • **API Reference:** [Patch Data Room – API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/update_convo_detail_cortex_conversation__convo_id__patch) Example request URL ``` https://blocky.theblockbrain.ai/cortex/conversation/689e2ee5ef2860b689633021 ``` Example request body ```json { "enableWebSearch": false } ``` This step should be executed after the web research phase is complete but before proceeding to the market opportunity analysis. Disabling web search ensures that subsequent agent tasks don't unnecessarily trigger additional web queries, improving performance and reducing API usage. ### Step 5: Generate Market Opportunities This operation triggers the market opportunity identification agent. * **Endpoint**: POST /cortex/completions/v2/user-input * **API Reference**: [Add User Messages – API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-completions/operation/add_user_messages_cortex_completions_user_input_post) Example request URL ``` https://blocky.theblockbrain.ai/cortex/completions/v2/user-input ``` Example request body ```json { "agentTaskId": "6858f2c03af6fad6eb14a490", "sessionId": "47286909-90df-426d-b53b-cefca26635ab", "convoId": "689e2ee5ef2860b689633021", "actionType": "agent", "messageId": "message_id_from_previous_step" } ``` Check the Prompt Template (`agentTaskId`) used for this query at [#opportunity-generation](#opportunity-generation "mention") ### Step 6: Retrieve Results with References This operation retrieves the completed analysis with source references links. • **Endpoint:** GET /cortex/message/{message\_id}/reference-content\ • **API Reference:** [Get Message Detail - API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_message_content_with_reference_document_cortex_message__message_id__reference_content_get) Example request URL ``` https://blocky.theblockbrain.ai/cortex/message/message_id/reference-content ``` The opportunities and email drafts are in the **`content`** of the response body, while the original company data is **`targetText`**. ### Step 7: Save as Insight (Optional) This operation saves the analysis as a permanent insight. • **Endpoint:** `POST /cortex/notes/generate?convo_id={convo_id}&latest_message_id={latest_message_id}&bot_id={bot_id}`\ \&#xNAN;**• API Reference**: [Generate Insight - API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-notes/operation/generate_chat_note_cortex_notes_generate_post) Example request URL ``` https://blocky.theblockbrain.ai/cortex/notes/generate?convo_id=689e2ee5ef2860b689633021&latest_message_id=message_id&bot_id=68514f586cd169f603f38a4e&is_pin=false&parent_path=root ``` ## 3. Best Practices 1. Create a new Data Room for each batch of companies to avoid carrying over context from previous analyses. 2. Use the prompt library to store opportunity detection prompts and ensure consistent use across UI and API. 3. Always disable web search after analysis completion to conserve resources. ## 4. Retrieving Necessary IDs The following IDs are required for the API calls described in the workflow above. #### Retrieving bot\_id from the UI 1. Log in to Blockbrain and navigate to the Bot Creator in the UI. 2. Select your Sales Navigator Bot. The bot details will include a field named **`bot ID`**. This is the value used in the **`/cortex/active-bot/bot_id/convo`** endpoint. #### Generating sessionId You will need to generate a random UUID from your client side and send it along with the request. You may use this sessionId for multiple API calls as shown in the workflow above and needn't generate new sessionId for each. Tip: You can also obtain a valid **`sessionId`** by logging in through the UI and then capturing it from the API requests in your browser's developer tools. This is useful during initial testing because you can use that value directly when experimenting with API calls. #### Retrieving agentTaskId To access the complete list of agent tasks for your bot call: GET **`/cortex/active-bot/bot_id`** (API Reference: [Get Active Bot Details API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-active-bot/operation/get_active_bot_details_cortex_active_bot__bot_id__get)). The response will contain an array of Agent Tasks associated with the bot, including their id, name, and prompt details. Key Agent Task IDs for Sales Navigator: * **Web Research:** `68b7e73788b8c14e131b543d` * **Relevant News:** `684039de199f41e44423ec8d` * **Market Opportunities:** `6858f2c03af6fad6eb14a490` * **Draft Emails:** `6858f2f8c2759562d831519d` Tip: You can also obtain an **`agentTaskId`** by logging in through the UI and then capturing it from the API requests in your browser's developer tools. The agentTaskId is unique for each selected prompt from the prompt library. ## Appendix: Prompts ### News Search ```markdown **Research Prompt: {{COMPANY}} - Time-Restricted Business Intelligence** **Core Requirements:** - Conduct comprehensive deep research analysis of recent news and developments pertaining to **{{COMPANY}}** (global market leader in braking systems for rail and commercial vehicles) - **Timeframe:** **Strictly from {{FROM DATE}} to {{TO DATE}}, inclusive** - **Mandatory Exclusion:** **Only include news items published within the specified date range. Exclude all content published outside this period** **Opportunity-Focused Areas:** - **Technology initiatives** - Digitalization, automation in mobility sector - **Regulatory challenges** - New safety/emissions standards requiring adaptation - **Market expansion** - Entry into new markets/segments - **Supply chain disruptions** - Requiring operational optimization - **Sustainability programs** - ESG transformation initiatives **Context for Opportunities:** - Focus on developments indicating need for external consulting expertise - Highlight strategic inflection points or complex challenges - Note any performance issues requiring intervention **Response Requirements:** - Answer very short - If no news found, just quickly state it - Only recent news within given timeframe - Include opportunity assessment per news item - Maximum 2-3 sentences per item with consulting relevance ``` ### Opportunity Generation ````markdown # **Role** You are a senior consultant at a top-tier management consultancy identifying consulting opportunities from recent company developments. ## **Task** Analyze recent news for the target company and generate a markdown-formatted opportunity report with two sections suitable for email/digital distribution. ## **Target Companies** **Process the companies from the input list that have recent, actionable strategic developments.** ## **Critical Output Requirements** ### **Reference Uniqueness Rules (HIGHEST PRIORITY):** - **MANDATORY:** Each reference/citation number (e.g., [[18.1]], [[34.1]]) can ONLY be used ONCE across ALL opportunities - **MANDATORY:** Every opportunity MUST have a UNIQUE reference - no reusing references - **MANDATORY:** If a reference has already been assigned to Opportunity A, it CANNOT be used for Opportunity B or C (at least not as the main reference) - **MANDATORY:** Track used references to ensure no duplication ### **Completeness Rules:** - **MANDATORY:** Only ever create Insights for the given company (including its subsidiaries and divisions) - **MANDATORY:** Every company in "Opportunity Overview" MUST appear in "Opportunity Details" - **MANDATORY:** The number of companies in both sections MUST be identical - **MANDATORY:** Every Opportunity MUST ALWAYS have it's matching reference and citation referenced - **MANDATORY:** For every reference and citation there always will ever only be one opportunity - **NEVER:** Get or create insights for any other company than the provided one (and its subsidiaries) - **NEVER** skip a company in the Details section if it appears in the Overview - **NEVER** get two opportunities from the same citation/reference - **NEVER** create two opportunities from the same source/reference/citation/link/file - **FLEXIBLE:** Number of opportunities will vary based on input - could be 0, 1, 2 or 3 ### **Use Markdown formatting:** - Headers: `## Opportunity Overview` and `## Opportunity Details` - Bold text: `**Company Name**` - Line breaks for spacing - Consistent indentation using spaces ## **Required Output Structure** ```javascript ## Opportunity Overview **[Company Name]** • Opportunity A • Opportunity B • Opportunity C ## Opportunity Details ### **[Company Name]** **Opportunity A:** [Strategic title] *Supporting news:* [Recent development driving this need] **Opportunity B:** [Strategic title] *Supporting news:* [Recent development driving this need] **Opportunity C:** [Strategic title] *Supporting news:* [Recent development driving this need] ```` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api.docs.blockbrain.ai/integration-best-practices/sales-opportunities.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.