Sales Opportunities
The purpose of this flow is to provide a step by step guide to integrating the Blockbrain API for automated sales signal detection and opportunity generation.
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: https://blocky.theblockbrain.ai/docs
Before proceeding with the workflow, ensure you have:
Configured your Sales Navigator bot.
Defined and saved the opportunity detection prompts in the prompt library.
Selected the appropriate LLM model in the bot settings (for example GPT-4).
Retrieved your
bot_id,agentTaskIdas 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
Example request URL
Example request body
Example response body
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
Example request URL
Example request body
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
Example request URL
Example request body
If enableStreaming is enabled, responses are returned token by token using Streaming. 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
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
Example request URL
Example request body
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
Example request URL
Example request body
Check the Prompt Template (agentTaskId) used for this query at Opportunity Generation
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
Example request URL
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}
• API Reference: Generate Insight - API Documentation
Example request URL
3. Best Practices
Create a new Data Room for each batch of companies to avoid carrying over context from previous analyses.
Use the prompt library to store opportunity detection prompts and ensure consistent use across UI and API.
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
Log in to Blockbrain and navigate to the Bot Creator in the UI.
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/convoendpoint.
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). 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:
68b7e73788b8c14e131b543dRelevant News:
684039de199f41e44423ec8dMarket Opportunities:
6858f2c03af6fad6eb14a490Draft 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
Opportunity Generation
Last updated
Was this helpful?