# Create Interview Request
Source: https://docs.usehindsight.com/api-reference/create-interview
POST /interviews
Creates an interview request. Buyer requests upsert the contact by email. When a `sequence_id`
is provided, the buyer contact is enrolled in the sequence and Hindsight's scheduling agent handles
outreach automatically. When only `interview_type_id` is provided, the request is created and the
survey link is returned without any outreach. Set `respondent_type` to `seller` to create an internal,
link-only seller request with no contact creation, email, Slack, or sequence outreach.
```text theme={null}
POST https://app.usehindsight.com/api/v1/interviews
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body:
{
"contact_email": "jane@acme.com", // required
"contact_name": "Jane Smith", // optional — creates/updates contact
"contact_context": { // optional — stored as contact notes, used by Paige
"title": "VP of Engineering",
"use_case": "Evaluating us for CI/CD automation"
},
"sequence_id": "seq_abc123", // required if no interview_type_id
"interview_type_id": "type_abc123", // required if no sequence_id
"deal_id": "deal_xyz789", // optional; mutually exclusive with salesforce_opportunity_id
"salesforce_opportunity_id": "006...", // optional; resolves a synced Hindsight deal
"respondent_type": "buyer", // optional: "buyer" (default) or "seller"
"objective": "Understand loss to Competitor X" // optional
}
201 Response:
{
"interview_request_id": 4821,
"contact_id": "contact_abc123",
"deal_id": "deal_xyz789",
"salesforce_opportunity_id": "006...",
"respondent_type": "buyer",
"survey_url": "https://app.usehindsight.com/survey?token=tok_xyz",
"survey_token": "tok_xyz",
"status": "sent" // "sent" = enrolled in sequence | "created" = link only
}
Rate limits: Organization-wide and per-API-key limits apply. Interview actions may consume a separate usage quota.
```
## Overview
Use this endpoint to programmatically trigger win-loss interviews. There are three paths:
* **Sequence path** (`sequence_id`) — Hindsight enrolls the contact and Paige handles email outreach automatically. The interview type, email template, and scheduling logic are inherited from the sequence.
* **Link-only path** (`interview_type_id`) — Creates the interview request and returns a survey link. No email is sent; you control delivery.
* **Seller path** (`respondent_type: "seller"`) — Creates an internal, link-only seller debrief. No contact is created, and the API does not send email, Slack messages, or sequence outreach.
Buyer contacts are upserted by email — if the contact already exists in your org, their record is updated with any new name or context you provide. Seller requests use the supplied email as the internal respondent and return `contact_id: null`.
## Request Parameters
### Required
You must provide either `sequence_id` or `interview_type_id`.
| Parameter | Type | Description |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `contact_email` | string | Email of the person to interview. For buyers, a contact is created or updated; for sellers, it identifies the internal respondent. |
| `sequence_id` | string | ID of the outreach sequence to enroll a buyer contact in. Paige sends the interview email automatically. Not supported for seller interviews. |
| `interview_type_id` | string | ID of the interview type (e.g. win-loss buyer, NPS). Use this for link-only requests where you handle delivery yourself. |
### Optional
| Parameter | Type | Description |
| --------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contact_name` | string | Full name of the person to interview. Used to create or update a buyer contact record. |
| `contact_context` | string \| object | Background context about a buyer contact, passed to Paige when conducting the interview. Accepts a plain string or a JSON object (serialized automatically). Stored in the buyer contact's notes and included in every interview prompt. |
| `deal_id` | string | Hindsight deal ID to associate the interview with. Mutually exclusive with `salesforce_opportunity_id`. |
| `salesforce_opportunity_id` | string | Salesforce Opportunity ID for an already-synced deal. Hindsight resolves it using the organization-scoped `deals.salesforce_id` field. Mutually exclusive with `deal_id`. |
| `respondent_type` | `"buyer"` \| `"seller"` | Defaults to `"buyer"`. Use `"seller"` to create an internal, link-only seller request (`external: false`). Seller requests cannot include `sequence_id`. |
| `objective` | string | Custom goal for this interview. Paige uses this as additional context (e.g. "Understand why we lost to Competitor X on pricing"). |
### Finding IDs
* **Sequence IDs** — Settings → Sequences in your Hindsight dashboard
* **Interview type IDs** — Settings → Interview Types
* **Deal IDs** — Use the [Get Deals](/api-reference/get-deals) endpoint or find them in the dashboard URL
* **Salesforce Opportunity IDs** — Salesforce `Opportunity.Id`; the deal must already be synced to Hindsight
## Contact Context
The `contact_context` field is the primary way to give Paige background on a buyer. This context is stored in the buyer contact's notes field and used in every interview prompt for that contact.
Pass anything relevant — role, company details, the deal they were involved in, why you're reaching out, or any other signal that helps Paige have a more informed conversation:
```json theme={null}
{
"contact_context": {
"title": "VP of Engineering",
"company_size": "500-1000 employees",
"use_case": "Evaluating us for CI/CD pipeline automation",
"evaluation_stage": "Completed a 30-day POC",
"primary_concern": "Integration complexity with existing toolchain"
}
}
```
You can also pass a plain string:
```json theme={null}
{
"contact_context": "Jane led the technical evaluation at Acme. She was enthusiastic about the product but raised concerns about our Jira integration."
}
```
## Response
| Field | Type | Description |
| --------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `interview_request_id` | integer | ID of the created interview request. |
| `contact_id` | string \| null | ID of the upserted buyer contact record; `null` for sellers. |
| `deal_id` | string \| null | Resolved Hindsight deal ID, or null. |
| `salesforce_opportunity_id` | string \| null | Salesforce Opportunity ID used to resolve the deal, or `null` when `deal_id` was used or no deal was supplied. |
| `respondent_type` | `"buyer"` \| `"seller"` | The audience for this interview request. |
| `survey_url` | string \| null | Direct link to the survey. Share this if you're handling delivery yourself. |
| `survey_token` | string \| null | Raw token used in the survey URL. |
| `status` | `"created"` \| `"sent"` | `sent` when enrolled in a sequence; `created` for link-only requests. |
## Rate Limits
Organization-wide and per-API-key limits apply. Interview actions may consume a separate usage quota. Handle `429 Too Many Requests` using the current response headers:
| Header | Description |
| ----------------------- | ---------------------------------------------------- |
| `X-RateLimit-Limit` | Requests allowed in the active response limit window |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
## Examples
```bash Sequence enrollment (with outreach) theme={null}
curl -X POST "https://app.usehindsight.com/api/v1/interviews" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_email": "jane@acme.com",
"contact_name": "Jane Smith",
"contact_context": {
"title": "VP of Engineering",
"use_case": "Evaluating us for CI/CD pipeline automation"
},
"sequence_id": "seq_abc123",
"deal_id": "deal_xyz789"
}'
```
```bash Link-only (no outreach) theme={null}
curl -X POST "https://app.usehindsight.com/api/v1/interviews" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_email": "jane@acme.com",
"contact_name": "Jane Smith",
"interview_type_id": "type_abc123",
"objective": "Understand why we lost this deal to Competitor X"
}'
```
```bash Salesforce seller debrief (internal, link-only) theme={null}
curl -X POST "https://app.usehindsight.com/api/v1/interviews" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_email": "alex.rep@acme.com",
"contact_name": "Alex Rep",
"interview_type_id": "seller_debrief_type_abc123",
"salesforce_opportunity_id": "006xx000001ABCdAAO",
"respondent_type": "seller",
"objective": "Capture the seller perspective on this closed deal."
}'
```
```javascript Node.js - Trigger interview on deal close theme={null}
const response = await fetch('https://app.usehindsight.com/api/v1/interviews', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HINDSIGHT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
contact_email: deal.buyer_email,
contact_name: deal.buyer_name,
contact_context: {
title: deal.buyer_title,
company: deal.account_name,
deal_value: deal.amount,
close_reason: deal.close_reason,
},
sequence_id: process.env.HINDSIGHT_WL_SEQUENCE_ID,
deal_id: deal.hindsight_id,
objective: `Win-loss analysis for ${deal.name}`,
}),
});
const { interview_request_id, survey_url, status } = await response.json();
console.log(`Interview ${status}: ${survey_url}`);
```
```python Python - Bulk trigger from CRM export theme={null}
import requests
import os
API_KEY = os.environ['HINDSIGHT_API_KEY']
SEQUENCE_ID = os.environ['HINDSIGHT_WL_SEQUENCE_ID']
def create_interview(contact_email, contact_name, deal_id=None, context=None):
response = requests.post(
'https://app.usehindsight.com/api/v1/interviews',
headers={'Authorization': f'Bearer {API_KEY}'},
json={
'contact_email': contact_email,
'contact_name': contact_name,
'contact_context': context,
'sequence_id': SEQUENCE_ID,
'deal_id': deal_id,
}
)
response.raise_for_status()
return response.json()
# Trigger interviews for recently closed deals
closed_deals = fetch_closed_deals_from_crm()
for deal in closed_deals:
result = create_interview(
contact_email=deal['buyer_email'],
contact_name=deal['buyer_name'],
deal_id=deal['hindsight_id'],
context={
'title': deal['buyer_title'],
'company': deal['account_name'],
'deal_size': deal['amount'],
}
)
print(f"{deal['name']}: {result['status']} — {result['survey_url']}")
```
## Common Patterns
### Trigger on CRM deal close
Connect Hindsight to your CRM via webhook or scheduled job to automatically send win-loss interviews whenever a deal closes. For already-synced Salesforce opportunities, pass `salesforce_opportunity_id` instead of maintaining a separate Hindsight deal-ID mapping. Pass only one of `salesforce_opportunity_id` and `deal_id`.
### Salesforce-only seller debriefs
Use a Salesforce Flow or outbound callout to invoke the seller path on Closed Won or Closed Lost. Set `respondent_type` to `"seller"`, pass the opportunity owner's email as `contact_email`, and store the returned `survey_url` on the Opportunity. This path creates an internal request without Slack or email delivery.
### Manual outreach with custom delivery
Use `interview_type_id` (no `sequence_id`) to get a survey link you can embed in your own email or send via your CRM. This is useful when you want full control over messaging or timing.
### Enriching contact context over time
If you call this endpoint multiple times for the same contact, `contact_context` overwrites the existing notes. To preserve prior context, read the contact's current notes first and merge before sending.
## Error Responses
| Code | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bad_request` | Missing or invalid field; an unknown `sequence_id`, `interview_type_id`, `deal_id`, or `salesforce_opportunity_id`; both deal identifiers; or a seller request with `sequence_id`. |
| `unauthorized` | Invalid or missing API key. |
| `rate_limit_exceeded` | Too many requests. Check `X-RateLimit-Reset` and retry after. |
| `internal_error` | Failed to create the contact record. |
```json theme={null}
{
"error": {
"code": "bad_request",
"message": "sequence_id not found"
}
}
```
# Bulk Export Deals
Source: https://docs.usehindsight.com/api-reference/export-deals
POST /deals/export
Generate a CSV file of deal data with flexible filtering and column selection.
Returns an export_id to track the job status and download the file when ready.
Bulk export deal data with flexible filtering and column selection. Generates a CSV file for download that includes all specified deal fields and custom properties.
```text theme={null}
POST https://app.usehindsight.com/api/v1/deals/export
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body:
{
"columns": ["name", "amount", "deal_status", "close_date", ...], // Array of column IDs to include
"filters": { // Optional filters
"deal_ids": ["deal_123", "deal_456"], // Specific deal IDs
"owner_ids": ["user_abc"], // Deal owner IDs
"status": ["Won", "Lost"], // Deal stages (Hindsight stage values)
"close_date": { // Date range
"from": "2026-01-01",
"to": "2026-03-31"
},
"amount": { // Deal size range
"min": 10000,
"max": 100000
},
"competitors": ["comp_123"], // Competitor IDs (any competitor on deal)
"deal_type": ["New Business", "Expansion"], // Deal types
"region": ["North America", "EMEA"], // Regions
"industry": ["Technology", "Finance"], // Industries
"product_labels": ["Product A"], // Product labels
"analyzed": true, // Only analyzed deals
"verified": true // Only verified analyses
}
}
200 Response:
{
"success": true,
"export_id": "exp_abc123",
"status": "pending",
"message": "Export job started successfully"
}
GET https://app.usehindsight.com/api/v1/deals/export/{export_id}
200 Response:
{
"export_id": "exp_abc123",
"status": "completed | pending | failed",
"download_url": "https://app.usehindsight.com/api/v1/deals/export/exp_abc123/download?token=...", // Available when status is "completed"
"rows_exported": 150,
"created_at": "2026-03-10T12:00:00Z",
"completed_at": "2026-03-10T12:02:30Z",
"expires_at": "2026-03-17T12:02:30Z" // Download URL expires in 7 days
}
Rate limits: Organization-wide and per-API-key limits apply. Exports may consume a separate usage quota.
```
## Overview
The bulk export API allows you to generate CSV files of your deal data with custom column selection and filtering. This is useful for:
* Creating custom reports for leadership
* Exporting data for external analysis tools
* Generating filtered deal lists for specific time periods or segments
* Backing up deal data
## Request Format
### Required Fields
| Parameter | Type | Description |
| --------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `columns` | string\[] | Array of column IDs to include in the export. See [Available Columns](#available-columns) for options. |
### Optional Filters
All filters are optional. If no filters are provided, all deals in your organization will be exported. These are the same canonical filter names and semantics used by GET `/deals`; export values are native JSON rather than JSON-encoded query strings.
#### Deal Identification
| Filter | Type | Description | Example |
| ---------- | --------- | -------------------------------------------- | -------------------------- |
| `deal_ids` | string\[] | Export specific deals by their Hindsight IDs | `["deal_123", "deal_456"]` |
#### People & Ownership
| Filter | Type | Description | Example |
| --------------- | --------- | -------------------------- | -------------------------- |
| `owner_ids` | string\[] | Filter by deal owner IDs | `["user_abc", "user_xyz"]` |
| `collaborators` | string\[] | Filter by collaborator IDs | `["user_def"]` |
#### Deal Attributes
| Filter | Type | Description | Example |
| ---------------- | --------- | ----------------------------------------------------------------------- | ------------------------------------------ |
| `status` | string\[] | Deal stages. Values are your CRM's stage names (e.g. `"Won"`, `"Lost"`) | |
| `deal_type` | string\[] | Types of deals | `["New Business", "Expansion", "Renewal"]` |
| `region` | string\[] | Geographic regions | `["North America", "EMEA", "APAC"]` |
| `industry` | string\[] | Customer industries | `["Technology", "Healthcare", "Finance"]` |
| `product_labels` | string\[] | Product labels associated with the deal | `["Product A", "Product B"]` |
> **Note on status values:** `status` filters come from your your specific workspace configuration.
#### Date & Amount Filters
| Filter | Type | Description | Example |
| ----------------- | ------ | --------------------- | -------------------------------------------- |
| `close_date` | object | Date range filter | `{"from": "2026-01-01", "to": "2026-03-31"}` |
| `close_date.from` | string | Start date (ISO 8601) | `"2026-01-01"` |
| `close_date.to` | string | End date (ISO 8601) | `"2026-03-31"` |
| `amount` | object | Deal amount range | `{"min": 10000, "max": 100000}` |
| `amount.min` | number | Minimum deal amount | `10000` |
| `amount.max` | number | Maximum deal amount | `100000` |
#### Competitive Intelligence
| Filter | Type | Description | Example |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------- | -------------------------- |
| `competitors` | string\[] | Filter by competitor IDs — matches deals where any of the specified competitors appear | `["comp_123", "comp_456"]` |
| `primary_competitor` | string\[] | Filter by competitor IDs — matches deals where the specified competitor is the primary competitor | `["comp_123"]` |
| `has_competitor` | boolean | Only deals with any competitor mentioned | `true` |
#### Analysis Filters
| Filter | Type | Description | Example |
| ---------- | ------- | ------------------------------ | ------- |
| `analyzed` | boolean | Only include analyzed deals | `true` |
| `verified` | boolean | Only include verified analyses | `true` |
#### CRM Filters (Advanced)
| Filter | Type | Description | Example |
| ---------------------------- | --------- | ----------------------------------------------------- | ------------------------------- |
| `salesforce_filters` | object\[] | Deal-level Salesforce properties (Opportunity object) | See [CRM Filters](#crm-filters) |
| `salesforce_filters_account` | object\[] | Account-level Salesforce properties (Account object) | See [CRM Filters](#crm-filters) |
| `hubspot_filters` | object\[] | Deal-level HubSpot properties | See [CRM Filters](#crm-filters) |
| `hubspot_filters_account` | object\[] | Account-level HubSpot properties (Company object) | See [CRM Filters](#crm-filters) |
### Filter Type Modifiers
For array-based filters, you can specify how they should be applied:
| Filter Type | Description | Example |
| -------------------- | ----------------------------------------- | ------------------------------------ |
| `is` / `is any of` | Matches if any value is present (default) | Include deals with competitor A OR B |
| `is not` / `exclude` | Excludes if any value is present | Exclude deals with competitor A or B |
| `include all of` | Matches only if all values are present | Include only deals with BOTH A AND B |
To use filter modifiers, append `_filter_type` to the filter name:
```json theme={null}
{
"competitors": ["comp_123", "comp_456"],
"competitors_filter_type": "include all of"
}
```
Supported `_filter_type` suffixes: `owner_filter_type`, `collaborator_filter_type`, `competitors_filter_type`, `primary_competitor_filter_type`, `product_filter_type`, `status_filter_type`, `deal_type_filter_type`, `region_filter_type`, `industry_filter_type`.
Existing integrations may continue using the [legacy filter aliases documented on GET `/deals`](/api-reference/get-deals#legacy-filter-aliases).
## Available Columns
### Standard Columns
| Column ID | Description |
| ------------------- | --------------------------------------------------------------------------- |
| `deal_id` | Hindsight deal ID (alias of `id`) |
| `salesforce_id` | Salesforce Opportunity ID |
| `name` | Deal name |
| `owner_id` | Deal owner ID |
| `all_competitors` | All competitors involved in the deal |
| `drivers` | Win/loss drivers and reasons |
| `features` | Product features discussed |
| `scorecard` | Complete win-loss analysis scorecard (includes all scores and explanations) |
| `deal_status` | Current deal stage |
| `previous_status` | Previous deal stage |
| `amount` | Deal value |
| `close_date` | Expected/actual close date (CSV header: "Close Date") |
| `created_at` | Deal creation date |
| `deal_analyzed` | Whether deal has been analyzed |
| `analysis_verified` | Reserved verification field; currently returns an empty value |
| `type` | Deal type (New Business, Expansion, Renewal) |
| `region` | Geographic region |
| `summary` | Complete structured deal summary |
> **Note:** The `scorecard` column includes all win-loss metrics (product fit, sales execution, relationship, price sensitivity, competitive intensity, customer fit, messaging fit, and messaging accuracy) with both scores and explanations.
### Dynamic Columns
These columns are generated based on your workspace configuration and CRM integrations:
#### CRM Deal Properties
Deal-level custom properties synced from your CRM (Opportunity/Deal object):
* Format: `crm_{property_id}`
* Example: `crm_lead_source`, `crm_sales_rep_region`
#### CRM Account Properties
Account-level properties synced from your CRM:
* HubSpot format: `crm_hubspot_account_{property_id}`
* Salesforce format: `crm_salesforce_account_{property_id}`
* Examples: `crm_hubspot_account_industry`, `crm_salesforce_account_annual_revenue`
#### Custom Metrics
Organization-specific metrics you've configured. Use the metric's **name** (not its internal ID) when specifying columns:
* Score format: `custom_metric_score_{metric_name}`
* Explanation format: `custom_metric_explanation_{metric_name}`
* Example: For a custom metric called "Strategic Fit": `custom_metric_score_Strategic Fit` or `custom_metric_explanation_StrategicFit`
#### Custom Answers
Custom questions you've set up for deal analysis. Use the question's **name** (not its internal ID):
* Format: `custom_answer_{answer_name}`
* Example: `custom_answer_Champion identified` or `custom_answer_ChampionIdentified` for a custom question called "Champion identified"
### Dynamic column example
The dynamic selector formats above are identical for GET `/deals` and bulk export. CRM selectors use the underlying CRM property ID; custom metrics and answers use their configured Hindsight names. Custom metric and answer name matching is case-insensitive and ignores spaces.
Only CRM properties synced into Hindsight are available. If a deal has no value for a requested CRM property, metric, or answer, its CSV cell is empty.
```bash theme={null}
curl -X POST https://app.usehindsight.com/api/v1/deals/export \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"columns": [
"deal_id",
"name",
"crm_LeadSource",
"crm_salesforce_account_Industry",
"custom_metric_score_Strategic Fit",
"custom_metric_explanation_Strategic Fit",
"custom_answer_Champion identified"
],
"filters": {
"analyzed": true
}
}'
```
Nested values such as `summary`, `scorecard`, `drivers`, `features`, and competitor data are JSON-encoded inside their CSV cells. Dynamic CRM properties, metric scores, metric explanations, and custom answers are emitted as individual CSV columns.
## Response
### Initial Response (POST)
When you submit an export request, you'll receive an export\_id and status:
```json theme={null}
{
"success": true,
"export_id": "exp_abc123",
"status": "pending",
"message": "Export job started successfully"
}
```
### Checking Export Status (GET)
Poll the export status endpoint to check when your export is ready:
```
GET /api/v1/deals/export/{export_id}
```
Response while processing:
```json theme={null}
{
"export_id": "exp_abc123",
"status": "pending",
"created_at": "2026-03-10T12:00:00Z"
}
```
Response when complete:
```json theme={null}
{
"export_id": "exp_abc123",
"status": "completed",
"download_url": "https://app.usehindsight.com/api/v1/deals/export/exp_abc123/download?token=...",
"rows_exported": 150,
"created_at": "2026-03-10T12:00:00Z",
"completed_at": "2026-03-10T12:02:30Z",
"expires_at": "2026-03-17T12:02:30Z"
}
```
Response if failed:
```json theme={null}
{
"export_id": "exp_abc123",
"status": "failed",
"error": "Export failed: Invalid column ID 'invalid_column'",
"created_at": "2026-03-10T12:00:00Z",
"failed_at": "2026-03-10T12:01:15Z"
}
```
### Download URL Expiration
* Download URLs are valid for 7 days after generation
* After expiration, you'll need to create a new export request
* The export record remains accessible via GET for 30 days
## CRM Filters
Use CRM filters to filter deals based on properties from your Salesforce or HubSpot integration. Deal-level and account-level properties use separate filter keys:
```json theme={null}
{
"salesforce_filters_account": [
{
"property": { "id": "Account.Industry", "map_to": "industry" },
"operator": "is",
"value": "COMPUTER_SOFTWARE"
}
],
"salesforce_filters": [
{
"property": { "id": "Amount" },
"operator": "is greater than",
"value": "50000"
}
]
}
```
**Deal vs. account filters:**
| Filter key | Object |
| ---------------------------- | ------------------------ |
| `salesforce_filters` | Opportunity (deal-level) |
| `salesforce_filters_account` | Account (account-level) |
| `hubspot_filters` | Deal (deal-level) |
| `hubspot_filters_account` | Company (account-level) |
The `property` field accepts either a string or an object:
```json theme={null}
{ "property": { "id": "field_name" } }
```
For ordinary CRM properties, the shorter string form is also accepted and is canonical:
```json theme={null}
{ "property": "field_name" }
```
Use the object form when a standard account property requires `map_to`.
**`map_to` for standard account properties:**
Some account properties (like industry or company name) are stored in a dedicated database column rather than the raw CRM payload. These require a `map_to` field pointing to the column name. Without it, the filter searches the raw CRM JSON and won't find data for these fields.
```json theme={null}
{
"property": {
"id": "Account.Industry",
"map_to": "industry"
}
}
```
**Supported operators:**
* `is`, `is not`
* `is greater than`, `is less than`
* `is greater than or equal to`, `is less than or equal to`
* `is before`, `is after` (for dates)
* `contains`, `does not contain` (for text)
## Rate Limits
Exports are subject to the organization-wide and per-API-key request limits. Export operations may also consume a separate usage quota.
When a request limit is exceeded, the API returns `429 Too Many Requests`. Handle it using `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; these public headers represent the active response limit.
## Examples
```bash Basic Export theme={null}
curl -X POST https://app.usehindsight.com/api/v1/deals/export \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"columns": ["name", "amount", "deal_status", "close_date", "owner_id"]
}'
```
```bash Filtered Export - Closed Deals Q1 2026 theme={null}
curl -X POST https://app.usehindsight.com/api/v1/deals/export \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"columns": [
"name", "amount", "deal_status", "close_date",
"drivers", "scorecard", "all_competitors", "summary"
],
"filters": {
"status": ["closedwon", "closedlost"],
"close_date": {
"from": "2026-01-01",
"to": "2026-03-31"
},
"analyzed": true
}
}'
```
```bash Export with Competitor Filter theme={null}
curl -X POST https://app.usehindsight.com/api/v1/deals/export \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"columns": [
"name", "amount", "deal_status", "all_competitors",
"drivers", "scorecard"
],
"filters": {
"competitors": ["comp_abc", "comp_xyz"],
"competitors_filter_type": "is any of",
"status": ["Lost"]
}
}'
```
```bash Check Export Status theme={null}
curl https://app.usehindsight.com/api/v1/deals/export/exp_abc123 \
-H "Authorization: Bearer YOUR_API_KEY"
```
```javascript Node.js - Start Export theme={null}
const response = await fetch('https://app.usehindsight.com/api/v1/deals/export', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
columns: ['name', 'amount', 'deal_status', 'close_date', 'owner_id'],
filters: {
status: ['closedwon', 'closedlost'],
close_date: {
from: '2026-01-01',
to: '2026-03-31'
}
}
})
});
const { export_id } = await response.json();
console.log('Export started:', export_id);
```
```javascript Node.js - Poll for Completion theme={null}
async function waitForExport(exportId) {
while (true) {
const response = await fetch(
`https://app.usehindsight.com/api/v1/deals/export/${exportId}`,
{
headers: { 'Authorization': `Bearer ${API_KEY}` }
}
);
const status = await response.json();
if (status.status === 'completed') {
console.log('Export ready!', status.download_url);
return status.download_url;
} else if (status.status === 'failed') {
throw new Error(`Export failed: ${status.error}`);
}
// Wait 5 seconds before checking again
await new Promise(resolve => setTimeout(resolve, 5000));
}
}
const downloadUrl = await waitForExport('exp_abc123');
```
```python Python - Complete Flow theme={null}
import requests
import time
API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://app.usehindsight.com/api/v1'
# Start export
response = requests.post(
f'{BASE_URL}/deals/export',
headers={
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
},
json={
'columns': ['name', 'amount', 'deal_status', 'close_date'],
'filters': {
'status': ['closewon', 'closedlost'],
'analyzed': True
}
}
)
export_id = response.json()['export_id']
print(f'Export started: {export_id}')
# Poll for completion
while True:
status_response = requests.get(
f'{BASE_URL}/deals/export/{export_id}',
headers={'Authorization': f'Bearer {API_KEY}'}
)
status = status_response.json()
if status['status'] == 'completed':
print(f'Export ready! Download from: {status["download_url"]}')
print(f'Rows exported: {status["rows_exported"]}')
break
elif status['status'] == 'failed':
print(f'Export failed: {status["error"]}')
break
print('Export still processing...')
time.sleep(5)
```
## Best Practices
1. **Column Selection**: Only request columns you need to minimize export size and processing time
2. **Polling Interval**: Wait 5-10 seconds between status checks to avoid rate limiting
3. **Download Promptly**: Download the file within 7 days before the URL expires
4. **Filter Early**: Apply filters to reduce export size rather than filtering after download
5. **Pagination Alternative**: For real-time data access, consider using the paginated `/deals` endpoint instead
## Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------------------ |
| 400 | Invalid request (e.g., invalid column ID, malformed filters) |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions |
| 404 | Export ID not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Example error response:
```json theme={null}
{
"error": "Invalid column IDs: unknown_column, invalid_field",
"status": 400
}
```
# Get Deals
Source: https://docs.usehindsight.com/api-reference/get-deals
GET /deals
Retrieve deals with flexible filtering, sorting, and pagination.
Returns deal objects with all their properties and relationships.
Use this for real-time data access and integrations.
Retrieve deals with flexible filtering, sorting, and pagination. Returns deal objects with all their properties and relationships.
```text theme={null}
GET https://app.usehindsight.com/api/v1/deals
Authorization: Bearer YOUR_API_KEY
Query Parameters:
# Pagination
page_size: number (default: 50, max: 100)
page_index: number (default: 0)
count: boolean (return only count, not data)
# Sorting
sort: string (column name to sort by)
sort_order: "asc" | "desc" (default: "desc")
# Column selection
columns: string (comma-separated column names, default: "*")
# Search
searchQuery: string (fuzzy search across deal names)
# Filters (same canonical names as bulk export; arrays/objects are JSON-encoded)
deal_ids: string (JSON array of Hindsight deal IDs)
owner_ids: string (JSON array of owner IDs)
owner_filter_type: "is any of" | "is not"
status: string (JSON array of deal stages)
status_filter_type: "is any of" | "is not"
close_date: string (JSON object: {"from": "2026-01-01", "to": "2026-03-31"})
amount: string (JSON object: {"min": 10000, "max": 100000})
competitors: string (JSON array of any competitor IDs)
competitors_filter_type: "is any of" | "is not" | "include all of"
primary_competitor: string (JSON array of primary competitor IDs)
deal_type: string (JSON array)
deal_type_filter_type: "is any of" | "is not"
region: string (JSON array)
region_filter_type: "is any of" | "is not"
industry: string (JSON array)
industry_filter_type: "is any of" | "is not"
product_labels: string (JSON array of product IDs)
product_filter_type: "is any of" | "is not" | "include all of"
analyzed: boolean
verified: boolean
# ... and more (see full filter list below)
200 Response:
[
{
"id": "deal_123",
"name": "Acme Corp - Enterprise License",
"amount": 50000,
"status_id": "negotiation",
"previous_status_id": "qualification",
"close_date": "2026-03-15",
"created_at": "2026-01-10T12:00:00Z",
"owner_id": "user_abc",
"salesforce_id": "006xxxxxxxxxxxx",
"hubspot_id": "789123456",
"deal_analyzed": true,
"analysis_verified": null,
"type": "New Business",
"region": "North America",
"summary": {
"executive_summary": "Executive summary text for the deal…",
"deal_overview": { "timeline": "…", "stakeholders": [], "deal_context": "…" },
"decision_drivers": [],
"competitive_landscape": [],
"key_quotes": [],
"lessons_learned": [],
"recommendations": []
},
"driver_ids": ["reason_456", "reason_789"],
"driver_names": ["Strong product fit", "Pricing competitiveness"],
"drivers": [
{
"name": "Strong product fit",
"tag": "Product",
"score": 3,
"sentiment": "positive",
"summary": "Unified survey + interview data favored our approach"
}
],
"competitors": [
{
"competitor_id": "comp_123",
"name": "Crayon",
"is_primary": true,
"is_incumbent": false,
"threat_level": 4,
"outcome": "lost_to_us",
"positioning_summary": "Positioned on price and AI-driven analysis",
"key_differentiators": "Executive-grade reporting"
}
],
"features": [
{
"name": "AI-driven interview analysis",
"product": "Core",
"impact_score": 3,
"sentiment": "positive",
"influence_summary": "Automated transcript synthesis was a differentiator"
}
],
"wl_product_fit_score": 4.2,
"wl_sales_execution_score": 3.8,
"wl_relationship_score": 4.5
// ... additional fields based on columns parameter
}
]
Rate limits: Organization-wide and per-API-key limits apply.
```
## Overview
Use this endpoint to programmatically access your deal data with real-time filtering and pagination. Unlike bulk export which generates a CSV file, this endpoint returns JSON objects immediately and is ideal for:
* Building custom dashboards and reports
* Syncing deal data to external systems
* Real-time data access for integrations
* Paginating through large datasets
For large datasets or CSV format, use the [Bulk Export Deals](/api-reference/export-deals) endpoint instead.
## Pagination
| Parameter | Type | Description | Default |
| ------------ | ------- | ------------------------------------- | ------- |
| `page_size` | number | Number of deals to return per page | 50 |
| `page_index` | number | Zero-based page index | 0 |
| `count` | boolean | If true, returns only the total count | false |
**Example:**
```
GET /deals?page_size=20&page_index=0 # First 20 deals
GET /deals?page_size=20&page_index=1 # Next 20 deals
GET /deals?count=true # Get total deal count
```
## Column Selection
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columns` | string | Comma-separated column IDs to return. The same IDs are accepted by bulk export. Use `*` for all columns. See [Available Columns](/api-reference/export-deals#available-columns). |
Limit returned data to only the fields you need to reduce response size and improve performance.
**Example:**
```
GET /deals?columns=deal_id,name,amount,deal_status,close_date,scorecard
GET /deals?columns=* # All columns (default)
```
A set of internal columns is always omitted from the response, even when you request `*` or name them explicitly: full-text search vectors, sync bookkeeping, sharing configuration, and raw aggregate blobs (e.g. `fts`, `joined_fts`, `keywords`, `sync_run_id`, `client_id`, `org_sharing_enabled`, `processing_in_progress`). The `close_date` column is returned under that name (it maps to the internal `proposal_due` field); you may request it as either `close_date` or `proposal_due`.
The relational columns `drivers`, `competitors`, and `features` return flattened arrays (see [Drivers, competitors, and features](#response-format) below) and are included with `*`. `summary` returns the complete structured deal-story object.
For a complete list of available columns (standard and dynamic), see the [Available Columns](/api-reference/export-deals#available-columns) section in the Bulk Export Deals documentation.
### CRM properties, custom metrics, and custom answers
GET `/deals` and bulk export accept the same dynamic column selectors:
| Data | Column selector | Uses |
| --------------------------- | ----------------------------------------- | ------------------------------ |
| CRM deal property | `crm_{property_id}` | CRM property ID |
| Salesforce account property | `crm_salesforce_account_{property_id}` | Salesforce Account property ID |
| HubSpot account property | `crm_hubspot_account_{property_id}` | HubSpot Company property ID |
| Custom metric score | `custom_metric_score_{metric_name}` | Hindsight metric name |
| Custom metric explanation | `custom_metric_explanation_{metric_name}` | Hindsight metric name |
| Custom answer | `custom_answer_{answer_name}` | Hindsight answer name |
CRM selectors use the underlying CRM property ID, not its display label. Custom metric and answer selectors use the names configured in Hindsight. Name matching is case-insensitive and ignores spaces.
Only CRM properties synced into Hindsight are available. A requested property, metric, or answer returns `null` when the deal has no corresponding value.
```bash Dynamic columns theme={null}
curl --get https://app.usehindsight.com/api/v1/deals \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "columns=deal_id,name,crm_LeadSource,crm_salesforce_account_Industry,custom_metric_score_Strategic Fit,custom_metric_explanation_Strategic Fit,custom_answer_Champion identified"
```
The JSON response uses the requested selector as the property name:
```json theme={null}
[
{
"deal_id": "deal_123",
"name": "Acme Corp",
"crm_LeadSource": "Event",
"crm_salesforce_account_Industry": "Software",
"custom_metric_score_Strategic Fit": 4,
"custom_metric_explanation_Strategic Fit": "Strong alignment with the target market.",
"custom_answer_Champion identified": "Yes"
}
]
```
## Search
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------ |
| `searchQuery` | string | Fuzzy search across deal names |
**Example:**
```
GET /deals?searchQuery=acme
```
## Filters
GET and bulk export use the same canonical filter names and semantics. GET passes arrays and objects as JSON-encoded query parameters; bulk export sends the same values as native JSON in its request body. Simple booleans such as `analyzed=true` do not need JSON array encoding.
### Deal Identification
| Filter | Type | Description | Example |
| -------------------------- | ------ | ------------------------------- | ------------------------- |
| `deal_ids` | string | JSON array of specific deal IDs | `["deal_123","deal_456"]` |
| `owner_ids` | string | JSON array of owner IDs | `["user_abc"]` |
| `owner_filter_type` | string | Filter type for owners | `is any of` |
| `collaborators` | string | JSON array of collaborator IDs | `["user_def"]` |
| `collaborator_filter_type` | string | Filter type for collaborators | `is any of` |
### Deal Attributes
| Filter | Type | Description | Example |
| ----------------------- | ------ | ------------------------- | ------------------------------- |
| `status` | string | JSON array of deal stages | `["Closed Won","Closed Lost"]` |
| `status_filter_type` | string | Filter type | `is any of` |
| `deal_type` | string | JSON array of deal types | `["New Business","Expansion"]` |
| `deal_type_filter_type` | string | Filter type | `is any of` |
| `region` | string | JSON array of regions | `["North America","EMEA"]` |
| `region_filter_type` | string | Filter type | `is any of` |
| `industry` | string | JSON array of industries | `["Technology","Healthcare"]` |
| `industry_filter_type` | string | Filter type | `is any of` |
| `product_labels` | string | JSON array of product IDs | `["prod_123"]` |
| `product_filter_type` | string | Filter type | `is any of` \| `include all of` |
### Date & Amount
| Filter | Type | Description | Example |
| ------------ | ------ | --------------------------- | ----------------------------------------- |
| `close_date` | string | JSON object with date range | `{"from":"2026-01-01","to":"2026-03-31"}` |
| `amount` | string | JSON object with min/max | `{"min":10000,"max":100000}` |
### Competitive Intelligence
| Filter | Type | Description | Example |
| -------------------------------- | ------- | ---------------------------------------------------------------- | -------------- |
| `competitors` | string | JSON array of IDs for competitors appearing anywhere on the deal | `["comp_123"]` |
| `competitors_filter_type` | string | `is any of` \| `is not` \| `include all of` | `is any of` |
| `primary_competitor` | string | JSON array of primary competitor IDs | `["comp_123"]` |
| `primary_competitor_filter_type` | string | `is any of` \| `is not` | `is any of` |
| `has_competitor` | boolean | Whether the deal has any competitor | `true` |
### Analysis
| Filter | Type | Description | Example |
| ---------- | ------- | -------------------------------------- | ------- |
| `analyzed` | boolean | Whether the deal has been analyzed | `true` |
| `verified` | boolean | Whether the analysis has been verified | `true` |
### Legacy filter aliases
Existing integrations do not need to change immediately. Both GET and bulk export continue to accept these earlier internal names:
| Legacy GET name | Canonical name |
| ---------------------------- | -------------------------------- |
| `ids` | `deal_ids` |
| `any_competitor` | `competitors` |
| `any_competitor_filter_type` | `competitors_filter_type` |
| `competitor` | `primary_competitor` |
| `competitor_filter_type` | `primary_competitor_filter_type` |
| `deal_analyzed` | `analyzed` |
| `analysis_verified` | `verified` |
Legacy boolean filters may still use JSON arrays such as `deal_analyzed=["true"]`.
### Win-Loss Scores
Filters for deal analysis scores (range queries):
| Filter | Format | Example |
| -------------------------------- | -------------------------------- | ------------------- |
| `wl_product_fit_score` | `{"min": number, "max": number}` | `{"min":3,"max":5}` |
| `wl_sales_execution_score` | `{"min": number, "max": number}` | `{"min":3,"max":5}` |
| `wl_relationship_score` | `{"min": number, "max": number}` | `{"min":3,"max":5}` |
| `wl_price_sensitivity_score` | `{"min": number, "max": number}` | `{"min":1,"max":3}` |
| `wl_competitive_intensity_score` | `{"min": number, "max": number}` | `{"min":3,"max":5}` |
| `wl_customer_fit_score` | `{"min": number, "max": number}` | `{"min":3,"max":5}` |
| `wl_messaging_fit_score` | `{"min": number, "max": number}` | `{"min":3,"max":5}` |
| `wl_messaging_accuracy_score` | `{"min": number, "max": number}` | `{"min":3,"max":5}` |
### CRM Filters (Advanced)
| Filter | Type | Description | Example |
| -------------------- | ------ | --------------------------------------- | ------------------------------- |
| `salesforce_filters` | string | JSON array of Salesforce filter objects | See [CRM Filters](#crm-filters) |
| `hubspot_filters` | string | JSON array of HubSpot filter objects | See [CRM Filters](#crm-filters) |
### Segments
| Filter | Type | Description | Example |
| --------------------- | ------ | ------------------------------- | ----------------------- |
| `segment` | string | JSON array of segment IDs | `["seg_123","seg_456"]` |
| `segment_filter_type` | string | `is any of` \| `include all of` | `is any of` |
## Sorting
| Parameter | Type | Description | Default |
| ------------ | ------ | ---------------------- | ----------- |
| `sort` | string | Column name to sort by | created\_at |
| `sort_order` | string | `asc` or `desc` | desc |
**Available sort columns:**
* `created_at` - Creation date
* `close_date` - Expected/actual close date
* `amount` - Deal value
* `name` - Deal name
* `wl_product_fit_score` - Product fit score
* `wl_sales_execution_score` - Sales execution score
* `wl_relationship_score` - Relationship score
* `wl_price_sensitivity_score` - Price sensitivity score
* `wl_competitive_intensity_score` - Competitive intensity score
* `wl_customer_fit_score` - Customer fit score
* `wl_messaging_fit_score` - Messaging fit score
* `wl_messaging_accuracy_score` - Messaging accuracy score
**Example:**
```
GET /deals?sort=close_date&sort_order=asc
GET /deals?sort=amount&sort_order=desc
```
## Response Format
### Standard Response
Returns an array of deal objects with all requested fields:
```json theme={null}
[
{
"id": "deal_123",
"name": "Acme Corp - Enterprise License",
"amount": 50000,
"status_id": "negotiation",
"previous_status_id": "qualification",
"close_date": "2026-03-15",
"created_at": "2026-01-10T12:00:00Z",
"owner_id": "user_abc",
"salesforce_id": "006xxxxxxxxxxxx",
"hubspot_id": "789123456",
"deal_analyzed": true,
"analysis_verified": null,
"type": "New Business",
"region": "North America",
"summary": {
"executive_summary": "Executive summary text for the deal…",
"deal_overview": { "timeline": "…", "stakeholders": [], "deal_context": "…" },
"decision_drivers": [],
"competitive_landscape": [],
"key_quotes": [],
"lessons_learned": [],
"recommendations": []
},
"driver_ids": ["reason_456"],
"driver_names": ["Price"],
"drivers": [
{
"name": "Price",
"tag": "Pricing",
"score": 2,
"sentiment": "negative",
"summary": "Price too high compared to competitor"
}
],
"competitors": [
{
"competitor_id": "comp_123",
"name": "Crayon",
"is_primary": true,
"is_incumbent": false,
"threat_level": 4,
"outcome": "lost",
"positioning_summary": "Main competitor evaluation",
"key_differentiators": null
}
],
"features": [
{
"name": "Executive-grade reporting",
"product": "Core",
"impact_score": 2,
"sentiment": "positive",
"influence_summary": "Filled a gap noted in incumbent tools"
}
],
"wl_product_fit_score": 4.2,
"wl_sales_execution_score": 3.8,
"wl_relationship_score": 4.5
}
]
```
### Drivers, competitors, and features
These three are **relational** fields, returned as flattened arrays (included with `*`, or by requesting the `drivers`, `competitors`, and `features` columns):
| Field | Shape |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `drivers` | `[{ name, tag, score, sentiment, summary }]` — decision drivers, strongest first. `sentiment` is `"positive" \| "negative" \| "neutral"`. `driver_ids` / `driver_names` are also returned as flat parallel arrays. |
| `competitors` | `[{ competitor_id, name, is_primary, is_incumbent, threat_level, outcome, positioning_summary, key_differentiators }]` — highest threat first. |
| `features` | `[{ name, product, impact_score, sentiment, influence_summary }]` — highest impact first. |
### Summary
`summary` returns the complete structured deal story, including `executive_summary`, `deal_overview`, `decision_drivers`, `competitive_landscape`, `key_quotes`, `lessons_learned`, and `recommendations`. It is `null` for deals that haven't been analyzed yet. Legacy plain-text summaries are returned as strings.
### Count Response
When `count=true`, returns only the total count:
```json theme={null}
142
```
## CRM Filters
For advanced filtering using CRM-specific properties:
```
GET /deals?salesforce_filters=[{"property":"Account.Industry","operator":"is","value":"Technology"}]
```
Salesforce filter object structure:
```json theme={null}
{
"property": "Account.Industry",
"operator": "is",
"value": "Technology"
}
```
Supported operators:
* `is`, `is not`
* `is greater than`, `is less than`
* `is greater than or equal to`, `is less than or equal to`
* `is before`, `is after` (for dates)
* `contains`, `does not contain` (for text)
## Rate Limits
Organization-wide and per-API-key limits apply. Handle `429 Too Many Requests` using `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.
## Examples
```bash Get Recent Deals theme={null}
curl "https://app.usehindsight.com/api/v1/deals?page_size=20&sort=created_at&sort_order=desc" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash Get Closed Deals with Analysis theme={null}
curl "https://app.usehindsight.com/api/v1/deals?status=%5B%22Closed%20Won%22%2C%22Closed%20Lost%22%5D&analyzed=true&page_size=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash Search Deals by Name theme={null}
curl "https://app.usehindsight.com/api/v1/deals?searchQuery=acme&page_size=10" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash Get Deal Count theme={null}
curl "https://app.usehindsight.com/api/v1/deals?count=true" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash Filter by Close Date and Amount theme={null}
curl "https://app.usehindsight.com/api/v1/deals?close_date=%7B%22from%22%3A%222026-01-01%22%2C%22to%22%3A%222026-03-31%22%7D&amount=%7B%22min%22%3A50000%7D" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```javascript Node.js - Get Paginated Deals theme={null}
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://app.usehindsight.com/api/v1';
async function getDeals(page = 0, pageSize = 50) {
const response = await fetch(
`${BASE_URL}/deals?page_size=${pageSize}&page_index=${page}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
return await response.json();
}
// Get first page
const deals = await getDeals(0, 50);
console.log(`Retrieved ${deals.length} deals`);
```
```javascript Node.js - Filter Closed Deals with Competitors theme={null}
const filters = {
status: JSON.stringify(['Closed Won', 'Closed Lost']),
status_filter_type: 'is any of',
has_competitor: 'true',
close_date: JSON.stringify({
from: '2026-01-01',
to: '2026-03-31'
})
};
const queryParams = new URLSearchParams(filters);
const response = await fetch(
`${BASE_URL}/deals?${queryParams.toString()}`,
{
headers: { 'Authorization': `Bearer ${API_KEY}` }
}
);
const deals = await response.json();
console.log(`Found ${deals.length} closed deals with competitor mentions`);
```
```javascript Node.js - Get Total Deal Count theme={null}
async function getTotalDeals() {
const response = await fetch(
`${BASE_URL}/deals?count=true`,
{
headers: { 'Authorization': `Bearer ${API_KEY}` }
}
);
const count = await response.json();
return count;
}
const total = await getTotalDeals();
console.log(`Total deals: ${total}`);
```
```python Python - Iterate Through All Deals theme={null}
import requests
import json
API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://app.usehindsight.com/api/v1'
def get_all_deals(filters=None):
"""Fetch all deals with pagination"""
all_deals = []
page = 0
page_size = 100
while True:
params = {
'page_size': page_size,
'page_index': page
}
# Add filters if provided
if filters:
params.update(filters)
response = requests.get(
f'{BASE_URL}/deals',
headers={'Authorization': f'Bearer {API_KEY}'},
params=params
)
response.raise_for_status()
deals = response.json()
if not deals:
break
all_deals.extend(deals)
print(f'Fetched page {page + 1}: {len(deals)} deals')
if len(deals) < page_size:
break
page += 1
return all_deals
# Get all analyzed deals from Q1 2026
filters = {
'analyzed': 'true',
'close_date': json.dumps({
'from': '2026-01-01',
'to': '2026-03-31'
})
}
deals = get_all_deals(filters)
print(f'Total deals retrieved: {len(deals)}')
```
```python Python - Filter by Win-Loss Scores theme={null}
import requests
import json
# Get high-performing deals (high product fit and execution)
filters = {
'wl_product_fit_score': json.dumps({'min': 4}),
'wl_sales_execution_score': json.dumps({'min': 4}),
'status': json.dumps(['Closed Won']),
'status_filter_type': 'is any of'
}
response = requests.get(
f'{BASE_URL}/deals',
headers={'Authorization': f'Bearer {API_KEY}'},
params=filters
)
deals = response.json()
print(f'Found {len(deals)} high-performing won deals')
for deal in deals[:5]:
print(f"- {deal['name']}: ${deal['amount']:,.0f}")
```
## Best Practices
1. **Use Pagination**: Always paginate through large datasets rather than requesting all at once
2. **Select Columns**: Use the `columns` parameter to only fetch fields you need
3. **Cache Counts**: If you need counts frequently, cache them with appropriate TTL
4. **Filter Server-Side**: Apply filters in the API request rather than fetching all data and filtering client-side
5. **Handle Rate Limits**: Implement exponential backoff when you receive 429 responses
6. **Use Bulk Export for Large Datasets**: If you need to analyze thousands of deals, use the bulk export endpoint instead
## Comparison: Get Deals vs Bulk Export
| Feature | GET /deals | POST /deals/export |
| ------------------- | ------------------------------------ | -------------------------------------------------------------------------------- |
| **Response Format** | JSON | CSV |
| **Response Time** | Immediate | 2-3 minutes |
| **Use Case** | Real-time access, integrations | Reports, analysis, backups |
| **Pagination** | Built-in | N/A (single file) |
| **Max Records** | Unlimited (paginated) | Unlimited |
| **Rate Limits** | Organization-wide and per-key limits | Organization-wide and per-key limits; exports may consume a separate usage quota |
| **Data Freshness** | Real-time | Snapshot at export time |
## Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------------------------ |
| 400 | Invalid request (e.g., invalid filter format, invalid column name) |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Example error response:
```json theme={null}
{
"message": "Invalid filter format: close_date must be a valid JSON object"
}
```
# Get Interview Status & Transcript
Source: https://docs.usehindsight.com/api-reference/get-interview
GET /interviews/{id}
Returns the current status of an interview request and, once completed, its full transcript.
Poll this endpoint to check whether a contact has completed their interview.
When `status` is `"completed"`, the `transcript` field contains the full conversation content.
```text theme={null}
GET https://app.usehindsight.com/api/v1/interviews/{id}
Authorization: Bearer YOUR_API_KEY
Path parameter:
id: integer — the interview_request_id returned from POST /interviews
200 Response:
{
"interview_request_id": 4821,
"contact_id": "contact_abc123",
"deal_id": "deal_xyz789",
"survey_url": "https://app.usehindsight.com/survey?token=tok_xyz",
"status": "created" | "sent" | "completed",
"objective": "string | null",
"email_sent_at": "2026-05-15T10:00:00Z | null",
"created_at": "2026-05-15T09:00:00Z",
"transcript": { // null unless status = "completed"
"document_id": "doc_abc123",
"content": "**Paige:** ...\n\n**Jane:** ...",
"created_at": "2026-05-16T14:30:00Z"
} | null
}
Rate limits: Organization-wide and per-API-key limits apply.
```
## Overview
Returns the current status of an interview request and, once completed, its full transcript.
Poll this endpoint to check whether a contact has responded. When `status` is `"completed"`, the `transcript.content` field contains the full conversation in markdown.
## Status Values
| Status | Meaning |
| ----------- | -------------------------------------------------------------- |
| `created` | Request exists but no outreach email has been sent yet. |
| `sent` | Email sent; waiting for the contact to complete the interview. |
| `completed` | Interview finished. `transcript` is populated. |
## Path Parameter
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------------ |
| `id` | integer | The `interview_request_id` returned when the interview was created via `POST /interviews`. |
## Response
| Field | Type | Description |
| ---------------------- | -------------- | ---------------------------------------------------- |
| `interview_request_id` | integer | ID of the interview request. |
| `contact_id` | string \| null | ID of the contact being interviewed. |
| `deal_id` | string \| null | Associated deal ID, or null. |
| `survey_url` | string \| null | Direct link to the survey for this contact. |
| `status` | string | `created`, `sent`, or `completed`. |
| `objective` | string \| null | Interview-specific goal, if set. |
| `email_sent_at` | string \| null | ISO timestamp when the outreach email was sent. |
| `created_at` | string | ISO timestamp when the request was created. |
| `transcript` | object \| null | Populated when `status` is `"completed"`. See below. |
### Transcript object
| Field | Type | Description |
| ------------- | ------ | -------------------------------------------------------------------------------------------- |
| `document_id` | string | ID of the document storing the transcript. |
| `content` | string | Full interview conversation in markdown. Speaker turns are formatted as `**Name:** message`. |
| `created_at` | string | ISO timestamp when the transcript was saved. |
## Polling
There is no webhook support yet — poll this endpoint to detect completion. A reasonable cadence for most use cases is every 5–15 minutes after sending.
```
POST /interviews → store interview_request_id
GET /interviews/{id} → poll until status = "completed"
→ read transcript.content
```
Avoid polling faster than once per minute — completions typically happen hours after the email is sent.
## Rate Limits
Organization-wide and per-API-key limits apply. Handle `429 Too Many Requests` using `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.
## Examples
```bash Check interview status theme={null}
curl "https://app.usehindsight.com/api/v1/interviews/4821" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```javascript Node.js - Poll until completed theme={null}
const API_KEY = process.env.HINDSIGHT_API_KEY;
async function waitForInterview(interviewRequestId, { intervalMs = 5 * 60 * 1000, maxAttempts = 48 } = {}) {
for (let i = 0; i < maxAttempts; i++) {
const res = await fetch(`https://app.usehindsight.com/api/v1/interviews/${interviewRequestId}`, {
headers: { 'Authorization': `Bearer ${API_KEY}` },
});
const data = await res.json();
if (data.status === 'completed') {
return data.transcript;
}
console.log(`[${i + 1}/${maxAttempts}] Status: ${data.status} — checking again in ${intervalMs / 60000}m`);
await new Promise((r) => setTimeout(r, intervalMs));
}
return null; // timed out
}
const transcript = await waitForInterview(4821);
if (transcript) {
console.log('Interview completed:', transcript.content);
}
```
```python Python - Fetch transcript once ready theme={null}
import requests
import time
API_KEY = 'YOUR_API_KEY'
def get_interview(interview_request_id):
response = requests.get(
f'https://app.usehindsight.com/api/v1/interviews/{interview_request_id}',
headers={'Authorization': f'Bearer {API_KEY}'}
)
response.raise_for_status()
return response.json()
def wait_for_completion(interview_request_id, interval_seconds=300, max_attempts=48):
for attempt in range(max_attempts):
data = get_interview(interview_request_id)
if data['status'] == 'completed':
return data['transcript']
print(f"[{attempt + 1}/{max_attempts}] Status: {data['status']}")
time.sleep(interval_seconds)
return None # timed out
transcript = wait_for_completion(4821)
if transcript:
print('Transcript:', transcript['content'])
```
## Error Responses
| Code | Description |
| --------------------- | -------------------------------------------------------------- |
| `unauthorized` | Invalid or missing API key. |
| `not_found` | Interview request not found, or it belongs to a different org. |
| `rate_limit_exceeded` | Too many requests. Check `X-RateLimit-Reset` and retry after. |
```json theme={null}
{
"error": {
"code": "not_found",
"message": "Interview request not found"
}
}
```
# Product Intelligence Export
Source: https://docs.usehindsight.com/api-reference/product-intelligence
GET /product-intelligence
Returns one row per product-feature association with its raw influence summary, feature taxonomy, deal, and account context. Without filters, returns associations of every sentiment.
Export individual product-feature requests with their original analysis, associated feature, deal, and customer context. Each row represents one feature-to-deal association, making it suitable for downstream clustering and product-request analysis.
```text theme={null}
GET https://app.usehindsight.com/api/v1/product-intelligence
Authorization: Bearer YOUR_API_KEY
Optional query parameters:
date_from: string (ISO 8601 association timestamp, inclusive)
date_to: string (ISO 8601 association timestamp, inclusive)
sentiment: "positive" | "negative" | "neutral"
tags: string (comma-separated tags, or repeat this parameter; all specified tags must match)
product: string (exact feature product)
product_area: string (exact feature product area)
200 Response:
{
"data": [
{
"id": "dfa_123",
"created_at": "2026-09-01T12:00:00Z",
"deal_id": "deal_123",
"feature_id": "feature_123",
"influence_summary": "The buyer needs SSO provisioning before they can move forward.",
"sentiment": false,
"tags": ["security", "must-have"],
"features": {
"id": "feature_123",
"name": "SCIM provisioning",
"description": "Automated user lifecycle management.",
"product": "Platform",
"product_area": "Identity"
},
"deals": {
"id": "deal_123",
"name": "Acme Enterprise",
"salesforce_id": "006xxxxxxxxxxxx",
"hubspot_id": "123456789",
"status": "Negotiation",
"amount": 50000,
"close_date": "2026-10-15T00:00:00Z",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-09-01T12:00:00Z",
"clients": {
"id": "client_123",
"name": "Acme Corp",
"salesforce_id": "001xxxxxxxxxxxx",
"hubspot_id": "987654321",
"industry": "Software",
"website_url": "https://acme.example"
}
}
}
],
"meta": {
"count": 1,
"sentiment": null,
"date_from": null,
"date_to": null,
"tags": [],
"product": null,
"product_area": null
}
}
Rate limits: Organization-wide limits apply.
```
## Overview
This endpoint returns the raw `influence_summary` for each feature association alongside CRM IDs and account context. It does not aggregate by feature, so a single feature requested in multiple deals appears as multiple rows.
When no filters are supplied, the response contains all product-feature associations available to the API key's organization, regardless of sentiment.
## Filters
| Parameter | Type | Description | Example |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `date_from` | string | Inclusive ISO 8601 lower bound for the association's `created_at` timestamp | `2026-01-01` |
| `date_to` | string | Inclusive ISO 8601 upper bound for the association's `created_at` timestamp | `2026-03-31T23:59:59Z` |
| `sentiment` | string | `positive`, `negative`, or `neutral`. Omit to return all sentiments. `neutral` returns associations with no sentiment recorded. | `negative` |
| `tags` | string | Comma-separated tags, or repeat the parameter. A row must contain every supplied tag. | `security,must-have` |
| `product` | string | Exact feature product | `Platform` |
| `product_area` | string | Exact feature product area | `Identity` |
**Examples:**
```bash theme={null}
# All product intelligence for the organization
curl https://app.usehindsight.com/api/v1/product-intelligence \
-H "Authorization: Bearer YOUR_API_KEY"
# Negative identity feedback created this quarter
curl --get https://app.usehindsight.com/api/v1/product-intelligence \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "date_from=2026-07-01" \
--data-urlencode "sentiment=negative" \
--data-urlencode "product_area=Identity"
# Requests carrying both tags
curl --get https://app.usehindsight.com/api/v1/product-intelligence \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "tags=security,must-have"
```
## Response fields
| Field | Description |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `influence_summary` | Raw feature-request or feature-impact summary extracted from the deal. |
| `sentiment` | `true` for positive, `false` for negative, or `null` when neutral/unspecified. |
| `tags` | Tags assigned to this feature association in this deal. |
| `features` | The associated Hindsight feature, including product taxonomy. |
| `deals.salesforce_id` | Salesforce Opportunity ID, when synced. |
| `deals.hubspot_id` | HubSpot Deal ID, when synced. |
| `deals.amount` | Deal value/ARR, when recorded. |
| `deals.close_date` | The deal's expected or actual close date. |
| `deals.clients.salesforce_id` | Salesforce Account ID, when synced. |
| `deals.clients.hubspot_id` | HubSpot Company ID, when synced. |
The endpoint returns a complete result set rather than a paginated collection. For especially large workspaces, narrow the result with the available filters.
# Create Response
Source: https://docs.usehindsight.com/api-reference/responses
POST /responses
Send a message and receive an AI-generated response with citations from your competitive intelligence data.
Hindsight automatically orchestrates multiple searches across deals, competitors, and knowledge base to provide comprehensive answers.
```text theme={null}
POST https://app.usehindsight.com/api/v1/responses
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body:
{
"messages": [
{ "role": "user | assistant | system", "content": "string" }
],
"stream": false
}
200 Response:
{
"message": {
"role": "assistant",
"content": "AI-generated response with inline citations",
"citations": [
{
"document_id": "string",
"document_name": "string",
"deal_id": "string | null",
"deal_name": "string | null",
"url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
"excerpt": "string"
}
]
},
"tool_calls": ["search_across_deals", "search_deal_documents"]
}
Rate limits: Organization-wide and per-API-key limits apply. Responses requests may consume a separate usage quota.
```
## Overview
The Responses endpoint is the highest-level way to use Hindsight. Send a natural-language question and Hindsight's AI orchestrates the underlying tools server-side — searching across deals, deal documents, competitive intel, and your knowledge base — then returns a single synthesized answer with inline citations.
Use it when you want a **complete, cited answer** rather than raw tool output. It's the right fit for Glean, Slack bots, search interfaces, and any app that should hand the user a finished response. If instead you want *your own* model to decide which tools to call, use the [MCP integration](/integrations/mcp).
```
POST https://app.usehindsight.com/api/v1/responses
```
## Request Body
| Field | Type | Required | Description |
| -------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `messages` | array | Yes | Conversation messages, oldest first. Each has a `role` and `content`. Include prior turns to give the AI context. |
| `messages[].role` | string | Yes | One of `user`, `assistant`, or `system`. |
| `messages[].content` | string | Yes | The message text. |
| `stream` | boolean | No | Stream the response as Server-Sent Events. Defaults to `false`. |
## Response
| Field | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| `message.role` | string | Always `assistant`. |
| `message.content` | string | The AI-generated answer, with inline citation markers. |
| `message.citations` | array | Source documents referenced in the answer (see [Citations](#citations)). |
| `tool_calls` | array | Names of the internal tools Hindsight called to produce the answer. |
### Citations
Each entry in `message.citations` traces a claim back to a source document:
| Field | Type | Description |
| --------------- | -------------- | ------------------------------------------------------ |
| `document_id` | string | Unique ID for the source document. |
| `document_name` | string | Human-readable document name. |
| `deal_id` | string \| null | Associated deal ID, if the document belongs to a deal. |
| `deal_name` | string \| null | Associated deal name, if applicable. |
| `url` | string | Link to view the document in Hindsight. |
| `excerpt` | string | The relevant passage the answer draws from. |
## Streaming
Set `stream: true` to receive the answer incrementally as Server-Sent Events. This is recommended for chat UIs where you want to render tokens as they arrive.
```json theme={null}
{
"messages": [{ "role": "user", "content": "..." }],
"stream": true
}
```
Events follow the SSE format:
```
data: {"type": "content_delta", "content": "Based on security"}
data: {"type": "content_delta", "content": " discussions"}
data: {"type": "citation", "citation": { "...": "..." }}
```
## Rate Limits
Organization-wide and per-API-key limits apply. Responses requests may consume a separate usage quota. On `429 Too Many Requests`, use `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` to back off and retry. See [Error Handling](/integrations/api#error-handling) for the full error format and codes.
```bash cURL theme={null}
curl -X POST https://app.usehindsight.com/api/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": "What security objections have we encountered with Enterprise customers?"
}
],
"stream": false
}'
```
```javascript Node.js theme={null}
const response = await fetch('https://app.usehindsight.com/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
messages: [{ role: 'user', content: 'What security objections have we encountered?' }],
stream: false
})
});
const data = await response.json();
console.log(data.message.content);
```
```python Python theme={null}
import requests
response = requests.post(
'https://app.usehindsight.com/api/v1/responses',
headers={
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
},
json={
'messages': [{'role': 'user', 'content': 'What security objections have we encountered?'}],
'stream': False
}
)
data = response.json()
print(data['message']['content'])
```
# Select Deal
Source: https://docs.usehindsight.com/api-reference/select-deal
POST /tools/select-deal
Returns lean, paginated deal rows for triage. Use `get-deal` to retrieve the full details for returned deal IDs.
Find analyzed deals using structured filters. This endpoint returns lean rows for triage; use [Get Deal](/api-reference/get-deal) with the returned `deal_id` values when you need summaries and competitor positioning.
```
POST https://app.usehindsight.com/api/v1/tools/select-deal
```
## Request Body
All fields are optional. `query`, `semantic_query`, and `segment_id` have compatibility constraints described below.
| Field | Type | Description |
| ---------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | Fuzzy match against the deal or client name. Cannot be combined with `semantic_query` or `segment_id`. |
| `semantic_query` | string | Search deal content by meaning, such as `deals lost over security compliance`. Returns a single ranked top-N result set and cannot be combined with `query` or `segment_id`. |
| `segment_id` | string | Filter by a segment ID. Cannot be combined with `query`. |
| `competitor_id` | string | Filter by competitor ID. |
| `deal_stage` | string or string\[] | One or more stage names, such as `Closed Won`. |
| `amount` | object | `{ "min": number, "max": number }`. |
| `close_date` | object | `{ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }`. |
| `type` | string | Filter by deal type. |
| `region` | string | Filter by region. |
| `owner_name` | string | Owner name or email. Use `me`, `my`, or `mine` for the authenticated user's deals. |
| `limit` | number | Results per page, from 1 to 50. Defaults to 20. |
| `page` | number | One-indexed page number. Defaults to 1. |
## Response
Each response contains a `results` array and paging metadata. A row is intentionally lean and includes identifiers and common deal attributes, not the full summary or competitor positioning.
```json theme={null}
{
"total_returned": 1,
"limit_applied": 20,
"page": 1,
"page_size": 20,
"has_more": false,
"next_page": null,
"results": [
{
"type": "deal",
"id": "deal_123",
"deal_id": "deal_123",
"name": "Acme Enterprise Renewal",
"client_name": "Acme Corp",
"stage": "Closed Lost",
"amount": 50000,
"close_date": "2026-06-30",
"deal_type": "Renewal",
"region": "North America",
"primary_competitor": "Example Competitor",
"url": "https://app.usehindsight.com/deals/deal_123/home"
}
]
}
```
When `has_more` is `true`, call the endpoint again with `page` set to `next_page`. Use `deal_id` from a result as input to [Get Deal](/api-reference/get-deal).
```bash cURL theme={null}
curl -X POST https://app.usehindsight.com/api/v1/tools/select-deal \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"competitor_id": "comp_123",
"deal_stage": ["Closed Won", "Closed Lost"],
"close_date": { "from": "2026-01-01", "to": "2026-06-30" },
"limit": 20,
"page": 1
}'
```
## Limits and Errors
Organization-wide and per-API-key limits apply. See [Rate limits](/integrations/api#rate-limits) for returned headers and retry guidance. Invalid input returns `400`; unauthorized or disallowed calls return `401` or `403`.
# Update Interview Request
Source: https://docs.usehindsight.com/api-reference/update-interview
PATCH /interviews/{id}
Updates context on an existing interview request. Accepts any combination of
`contact_context`, `contact_name`, and `objective`. At least one field must be provided.
- `contact_context` and `contact_name` update the contact record associated with the request.
Context is stored in the contact's notes field and used by Paige in every future interview prompt for that contact.
- `objective` updates the interview-specific goal on the request itself.
```text theme={null}
PATCH https://app.usehindsight.com/api/v1/interviews/{id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Path parameter:
id: integer — the interview_request_id returned from POST /interviews
Request body (at least one field required):
{
"contact_context": { ... } | "string", // overwrites contact notes
"contact_name": "Jane Smith", // updates contact display name
"objective": "string" // updates interview-specific goal
}
200 Response:
{
"interview_request_id": 4821
}
Rate limits: Organization-wide and per-API-key limits apply. Interview actions may consume a separate usage quota.
```
## Overview
Use this endpoint to update context on an interview request after it has been created.
* **`contact_context`** and **`contact_name`** update the contact record linked to the request. Context is stored in the contact's notes field and included in every future interview prompt Paige runs for that contact.
* **`objective`** updates the interview-specific goal on the request itself, giving Paige a targeted focus for this particular interview.
At least one field must be provided. Fields not included in the request are left unchanged.
## Path Parameter
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------------ |
| `id` | integer | The `interview_request_id` returned when the interview was created via `POST /interviews`. |
## Request Body
| Field | Type | Description |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contact_context` | string \| object | Updated context about the contact. **Overwrites** the existing contact notes — merge manually if you want to preserve prior context. Accepts a plain string or JSON object (serialized automatically). |
| `contact_name` | string | Updated display name for the contact. |
| `objective` | string | Updated goal for this specific interview. Paige uses this when generating questions and conducting the conversation. |
`contact_context` overwrites the contact's existing notes rather than merging. If you want to preserve prior context, read the contact's current notes first and include them in your update.
## Response
| Field | Type | Description |
| ---------------------- | ------- | ------------------------------------ |
| `interview_request_id` | integer | ID of the updated interview request. |
## Rate Limits
Organization-wide and per-API-key limits apply. Interview actions may consume a separate usage quota. Handle `429 Too Many Requests` using `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.
## Examples
```bash Update contact context theme={null}
curl -X PATCH "https://app.usehindsight.com/api/v1/interviews/4821" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_context": {
"title": "CTO",
"evaluation_notes": "Completed 30-day POC, main concern is pricing"
}
}'
```
```bash Update objective only theme={null}
curl -X PATCH "https://app.usehindsight.com/api/v1/interviews/4821" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"objective": "Focus on why pricing was a blocker vs. Competitor X"
}'
```
```bash Update all fields theme={null}
curl -X PATCH "https://app.usehindsight.com/api/v1/interviews/4821" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_name": "Jane Smith",
"contact_context": {
"title": "CTO",
"evaluation_notes": "Completed POC, flagged pricing and Jira integration"
},
"objective": "Understand the pricing objection and Competitor X comparison"
}'
```
```javascript Node.js - Update after CRM enrichment theme={null}
const interviewRequestId = 4821; // stored from POST /interviews response
await fetch(`https://app.usehindsight.com/api/v1/interviews/${interviewRequestId}`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${process.env.HINDSIGHT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
contact_context: {
title: enrichedContact.title,
linkedin: enrichedContact.linkedinUrl,
evaluation_notes: deal.internalNotes,
},
objective: `Win-loss: understand loss to ${deal.competitorName}`,
}),
});
```
```python Python - Enrich context before interview sends theme={null}
import requests
def update_interview_context(interview_request_id, contact_data, objective=None):
payload = {
'contact_context': {
'title': contact_data.get('title'),
'seniority': contact_data.get('seniority'),
'notes': contact_data.get('notes'),
}
}
if objective:
payload['objective'] = objective
response = requests.patch(
f'https://app.usehindsight.com/api/v1/interviews/{interview_request_id}',
headers={'Authorization': f'Bearer {API_KEY}'},
json=payload
)
response.raise_for_status()
return response.json()
```
## Error Responses
| Code | Description |
| --------------------- | -------------------------------------------------------------- |
| `bad_request` | No fields provided, or invalid JSON. |
| `unauthorized` | Invalid or missing API key. |
| `not_found` | Interview request not found, or it belongs to a different org. |
| `rate_limit_exceeded` | Too many requests. Check `X-RateLimit-Reset` and retry after. |
```json theme={null}
{
"error": {
"code": "not_found",
"message": "Interview request not found"
}
}
```
# Upload to Deal
Source: https://docs.usehindsight.com/api-reference/upload-deal-document
POST /deals/documents
Associate documents with specific deals for win-loss analysis.
Audio and video files are automatically transcribed.
Documents are processed and used to enrich deal insights.
Associate documents with specific deals for win-loss analysis. Audio and video files are automatically transcribed.
```text theme={null}
POST https://app.usehindsight.com/api/v1/deals/documents
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
Request fields (multipart/form-data):
file_name: string (required)
file_url: string (uri) — URL to fetch file from
file: binary — binary file content (alternative to file_url)
content_type: string (required) — MIME type, e.g. application/pdf, audio/mpeg, video/mp4
deal_id: string — Hindsight deal ID
salesforce_id: string — Salesforce Opportunity ID
hubspot_id: string — HubSpot Deal ID
source: gong | clari | fathom | fireflies | avoma | outreach | gmail | Salesforce | Hubspot | api
Provide exactly one of: deal_id, salesforce_id, or hubspot_id.
200 Response:
{
"document": {
"id": "doc_abc123",
"file_name": "Discovery Call Recording.mp3",
"status": "processing | ready | failed",
"type": "asset | intel",
"url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
"created_at": "2026-02-10T12:00:00Z"
},
"run_id": "run_xyz789"
}
Rate limits: Organization-wide and per-API-key limits apply. Uploads may consume a separate usage quota.
```
## Deal Identification
You can identify the deal using one of three methods:
| Parameter | Description |
| --------------- | --------------------------------------------------- |
| `deal_id` | Hindsight's internal deal ID |
| `salesforce_id` | Salesforce Opportunity ID (e.g., `006xxxxxxxxxxxx`) |
| `hubspot_id` | HubSpot Deal ID |
## Source Options
The `source` field determines the icon displayed and helps with document organization:
| Source | Description |
| ------------ | -------------------- |
| `gong` | Gong call recordings |
| `clari` | Clari |
| `fathom` | Fathom AI |
| `fireflies` | Fireflies.ai |
| `avoma` | Avoma |
| `outreach` | Outreach |
| `gmail` | Gmail |
| `Salesforce` | Salesforce |
| `Hubspot` | HubSpot |
| `api` | API upload |
## Supported File Types
| Category | Formats | Notes |
| --------- | ------------------------------ | ------------------------------------- |
| Documents | PDF, DOCX, PPTX, XLSX, MD, TXT | Parsed and chunked for search |
| Audio | MP3, WAV, M4A | Automatically transcribed via Whisper |
| Video | MP4 | Automatically transcribed via Whisper |
```bash cURL theme={null}
curl -X POST https://app.usehindsight.com/api/v1/deals/documents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_name": "Discovery Call Recording.mp3",
"file_url": "https://example.com/recording.mp3",
"content_type": "audio/mpeg",
"salesforce_id": "006xxxxxxxxxxxx",
"source": "gong"
}'
```
```javascript Node.js theme={null}
const response = await fetch('https://app.usehindsight.com/api/v1/deals/documents', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
file_name: 'Discovery Call Recording.mp3',
file_url: 'https://example.com/recording.mp3',
content_type: 'audio/mpeg',
salesforce_id: '006xxxxxxxxxxxx',
source: 'gong'
})
});
const data = await response.json();
console.log(`Document uploaded: ${data.document.id}`);
console.log(`Processing run: ${data.run_id}`);
```
```python Python theme={null}
import requests
response = requests.post(
'https://app.usehindsight.com/api/v1/deals/documents',
headers={
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
},
json={
'file_name': 'Discovery Call Recording.mp3',
'file_url': 'https://example.com/recording.mp3',
'content_type': 'audio/mpeg',
'salesforce_id': '006xxxxxxxxxxxx',
'source': 'gong'
}
)
data = response.json()
print(f"Document uploaded: {data['document']['id']}")
print(f"Processing run: {data['run_id']}")
```
# Upload to Knowledge Base
Source: https://docs.usehindsight.com/api-reference/upload-library-document
POST /documents/library
Upload competitive intelligence documents, assets, and other files to your library.
Documents are automatically processed, chunked, and indexed for search.
Upload competitive intelligence documents, assets, and battlecards to your library.
```text theme={null}
POST https://app.usehindsight.com/api/v1/documents/library
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
Request fields (multipart/form-data):
file_name: string (required)
file_url: string (uri) — URL to fetch file from
file: binary — binary file content (alternative to file_url)
content_type: string (required) — MIME type, e.g. application/pdf
type: asset | intel (required)
competitor_id: string — Hindsight competitor ID
competitor_name: string — resolved to competitor_id automatically
source: drive | notion | confluence | onedrive | sharepoint | vanta | url | zapier | api
200 Response:
{
"document": {
"id": "doc_abc123",
"file_name": "Competitor X Pricing Guide.pdf",
"status": "processing | ready | failed",
"type": "asset | intel",
"url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
"created_at": "2026-02-10T12:00:00Z"
},
"run_id": "run_xyz789"
}
Rate limits: Organization-wide and per-API-key limits apply. Uploads may consume a separate usage quota.
```
## Document Types
| Type | Description |
| ------- | ------------------------------------------------------------- |
| `asset` | Sales enablement content like battlecards, one-pagers, guides |
| `intel` | Competitive intelligence gathered from external sources |
## Source Options
The `source` field determines the icon displayed in the Hindsight UI:
| Source | Description |
| ------------ | ----------------- |
| `drive` | Google Drive |
| `notion` | Notion |
| `confluence` | Confluence |
| `onedrive` | OneDrive |
| `sharepoint` | SharePoint |
| `vanta` | Vanta |
| `url` | Web URL |
| `zapier` | Zapier automation |
| `api` | API upload |
```bash cURL theme={null}
curl -X POST https://app.usehindsight.com/api/v1/documents/library \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file_name=Competitor X Pricing Guide.pdf" \
-F "file_url=https://example.com/document.pdf" \
-F "content_type=application/pdf" \
-F "type=asset" \
-F "competitor_name=Competitor X" \
-F "source=drive"
```
```javascript Node.js theme={null}
const formData = new FormData();
formData.append('file_name', 'Competitor X Pricing Guide.pdf');
formData.append('file_url', 'https://example.com/document.pdf');
formData.append('content_type', 'application/pdf');
formData.append('type', 'asset');
formData.append('competitor_name', 'Competitor X');
formData.append('source', 'drive');
const response = await fetch('https://app.usehindsight.com/api/v1/documents/library', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`
},
body: formData
});
const data = await response.json();
console.log(`Document uploaded: ${data.document.id}`);
```
```python Python theme={null}
import requests
response = requests.post(
'https://app.usehindsight.com/api/v1/documents/library',
headers={'Authorization': f'Bearer {API_KEY}'},
data={
'file_name': 'Competitor X Pricing Guide.pdf',
'file_url': 'https://example.com/document.pdf',
'content_type': 'application/pdf',
'type': 'asset',
'competitor_name': 'Competitor X',
'source': 'drive'
}
)
data = response.json()
print(f"Document uploaded: {data['document']['id']}")
```
# Analyze Deals
Source: https://docs.usehindsight.com/deals-quickstart
Connect your sales tools and set up AI-powered deal analysis in 4 steps
Deal analysis is the foundation of Hindsight. Connect your sources and Hindsight aggregates the calls, emails, CRM records, and documents for each deal into **one verified record** — a *Deal Review* — that powers everything else: your library, the Compete Agent, custom AI, and Plays.
![Deals home]()
Connect your sales tools to automatically import deals, calls, and customer
data. Hindsight integrates with all major CRM and sales platforms. **Popular
Integrations:**
* **Salesforce or HubSpot**: Automatic deal import and
analysis. See [Salesforce Integration](/integrations/salesforce-integration) [HubSpot Integration](/integrations/hubspot-integration)
* **Gong, Clari, Outreach, Fathom**: Sales call transcription and insights. See [Gong Integration](/integrations/gong)
* **API**: Push any document or transcript straight onto a deal — useful for sources Hindsight doesn't integrate with natively. See [Upload to a deal](/integrations/api#upload-to-deal).
**Control what comes across from the [CRM Settings page](https://app.usehindsight.com/settings/properties).** Define which deals get pulled, which objects and properties are imported, and where Hindsight writes insights back to your CRM.
Tailor Hindsight's analysis to match your business needs.
![Metric scores and answer rollups]()
**Add Custom [Answers](https://app.usehindsight.com/settings/custom-answers) & [Metrics](https://app.usehindsight.com/settings/custom-metrics) from Library:**
* Browse our pre-built library of [answers](https://app.usehindsight.com/settings/custom-answers) and [metrics](https://app.usehindsight.com/settings/custom-metrics)
* Select the insights most relevant to your sales process and win-loss objectives
* Customize how data is extracted and displayed
**Optional: Add Your Own Tags (We'll Auto-Detect):**
* **[Features](https://app.usehindsight.com/settings/features)**: Define product capabilities to track across deals
* **[Decision Drivers](https://app.usehindsight.com/settings/reasons)**: Set up factors that influence buying decisions
* **[Competitors](https://app.usehindsight.com/settings/competitors)**: Add competitors for automatic mention detection
Hindsight will automatically detect and tag these elements in your deal conversations.
![Product insights]()
Put your insights into action with skills and automated workflows.
**Skills:**
* Run pre-built analysis skills on your deals
* Generate battlecards, reports, and competitive insights
* Extract specific data points across multiple deals
**Workflows:**
* Automate recurring analysis tasks
* Set up triggers based on deal events
* Schedule regular reports and updates
***
## Sources for deal context
Hindsight builds each Deal Review from whatever you connect. Your CRM is the only required source; everything else is optional enrichment.
| Type | Sources |
| -------------- | ---------------------------------------------------- |
| CRM (required) | Salesforce, HubSpot |
| Calls | Gong, Clari, Outreach Kaia, Fathom, Fireflies, Avoma |
| API | Push any document or transcript directly onto a deal |
![Deal documents from connected sources]()
Need to bring in a source Hindsight doesn't integrate with natively — a data warehouse export, a custom note-taker, an internal tool? Use the **API** to attach documents and transcripts to a deal by `deal_id`, `salesforce_id`, or `hubspot_id`. PDFs, Office files, Markdown, audio, and video are all accepted, and recordings are transcribed automatically. See [Upload to a deal](/integrations/api#upload-to-deal).
***
## When & how Deal Reviews run
Deal analysis runs automatically — you don't trigger each review by hand.
* **Sync cadence** — Hindsight pulls the latest from your connected integrations **every 12 hours** while a deal is open, and continues for **14 days after it closes**, so late-arriving calls and notes still make it in.
* **Re-analysis triggers** — a Deal Review re-runs on **every stage change** (including a move to *Closed Won* / *Closed Lost*), when a deal meets your **auto-import criteria**, and whenever **new context is added** — an uploaded document, an API push, or a completed win-loss interview.
* **Manual runs** — you can re-analyze any deal on demand after new information lands, or backfill historical deals that were never analyzed.
Each review produces a structured deal story — executive summary, timeline, stakeholders, decision drivers, competitive landscape, key quotes, and lessons learned — and can sync win/loss reasons and custom fields back to your CRM. See the full [Deal Reviews guide](/platform/review/deal-reviews) for the complete breakdown.
![Individual deal report]()
***
## Ways to analyze your deals
Once your deals are analyzed, there are two ways to get insight out of them — pick based on whether you want an open-ended answer or a standing view.
### 1. Ask AI
Query the verified layer in natural language and let Hindsight pick the right tools across your deals, library, and the web.
* **In-app** — use [Chat](https://app.usehindsight.com/chat) for ad-hoc questions ("why did we lose enterprise deals to Crayon last quarter?").
* **Over MCP** — point Claude, ChatGPT, or your own agent at Hindsight's tools and analyze deals from inside your existing workflow. See [MCP](/integrations/mcp).
* **Compose & schedule** — save a working prompt as a **Skill** and run it on demand or on a recurring cadence, delivered to Slack or email. See [Skills and Workflows](/guides/recipes).
### 2. Dashboard
For standing metrics, the dashboard turns your analyzed deals into **pre-built charts** — no prompting required. Filter by date, segment, or competitor and read win rate, revenue, and the drivers behind outcomes at a glance.
![Win-loss dashboard]()
The dashboard also rolls up your custom **metric scores** and **answers** across every analyzed deal, so configured rubrics and free-form questions become trended, aggregate views.
![Metric scores and answer rollups]()
***
### What's Next?
Seed the competitor-scoped knowledge base your AI draws from for battlecards and answers.
Create competitive assets like battlecards, comparison sheets, and objection handlers.
Set up automated win-loss interviews to gather deeper insights from your deals.
# Set Up Library
Source: https://docs.usehindsight.com/guides/knowledge-base-setup
How to seed and manage your knowledge base for accurate AI answers
Hindsight's AI runs best on verified data. The quality of answers your team gets — in Slack, in battlecards, in deal reviews — depends directly on what you put in your knowledge base.
This guide covers how to seed and manage that knowledge base.
**Deal documents are part of your library too — but scoped separately.** The calls, transcripts, and files Hindsight ingests per deal live on each deal's record and are organized **by deal**, not by competitor. You manage those as part of [Analyze Deals](/deals-quickstart), not here. This guide covers the **competitor-scoped** library (`/assets` and `/intel`) the AI draws on for battlecards, enablement, and chat answers.
***
## What the Knowledge Base Is
Hindsight maintains a trusted repository of information about your company and your competitors. This is the primary source the AI draws from when enabling reps, generating battlecards, and answering questions in chat.
There are two sections, which you can find under "Library" in the sidebar:
* **/assets** — Your content library. Sales playbooks, battlecards, one-pagers, messaging docs. Organized by competitor.
* **/intel** — Public and web-sourced competitive data. Tracked URLs, product pages, press releases, release notes.
Everything in both sections is categorized by competitor. The AI uses this structure to retrieve the right context for the right question.
***
## Importing Existing Content
If your team already has competitive content sitting in Google Drive, Notion, or Confluence, you can import it directly into `/assets`.
**To get started:**
1. Go to [Assets](https://app.usehindsight.com/assets) and connect your integration (Drive, Notion, or Confluence).
2. Select the files you want to import.
3. Tag each file with a competitor. This tells Hindsight which competitive context the file belongs to.
**Tagging rules:**
* Files about a competitor (battlecards, objection handling, pricing comparisons) go under that competitor's tag.
* Files about your own company (your playbook, your messaging, your ICP) go under **"You"**.
* Untagged files can be categorized after import. Hindsight will flag them.
This seeds your knowledge base with existing knowledge. The AI prioritizes your asset library when answering rep questions — so the more complete it is, the better the answers.
> **Best format:** Markdown. Hindsight parses and retrieves markdown most reliably. If you're importing rich-text docs, clean formatting helps.
> **Clean Separation:** It's better to have multiple short, cleanly titled documents for a competitor than one long doc. This allows Hindsight to pull the most relevant context for each question.
***
## Mapping Competitive Websites
The `/intel` library is for public web data. Competitor product pages, pricing pages, release notes, G2 profiles — anything you want Hindsight to monitor and keep current.
**To add a URL:**
* Go to [Intel](https://app.usehindsight.com/intel) and add a URL directly, or
* Add URLs from a Workflow, or
* Ask the AI Assistant to pull a page and save it
Each URL has a **refresh frequency** you can configure. Hindsight re-fetches on that schedule and updates the record automatically. This is "approved" data — the AI can cite it in responses.
Set shorter refresh intervals for fast-moving pages like competitor pricing or changelog feeds. Set longer intervals for stable content like company overview pages.
***
## Saving Pages from the AI Assistant
When you're in a chat and Hindsight cites a URL, you can save it to your intel library in one click.
This is the fastest way to grow your knowledge base organically. If the AI found it useful, it's worth keeping.
***
## Creating Hindsight-Native Content
You can also write content directly inside Hindsight. This is the simplest path and gives Hindsight the most control over formatting, structure, and updates.
Native content is easier to maintain. When something changes, you update it in one place and it's immediately current for every rep and every workflow that references it.
[See the guide to creating native content →](/guides/creating-assets)
***
## Keeping It Current
Hindsight syncs the latest versions of your intel URLs automatically based on your refresh settings. For asset library content, updates from connected integrations pull through when you re-sync.
The knowledge base is only as good as its freshest entry. Stale battlecards are one of the top reasons reps stop trusting competitive tools. Hindsight is designed to fix that — but it requires intentional setup up front.
***
## Quick Reference
| Section | What Goes Here | Source |
| --------------------------------------------- | ------------------------------------------ | ------------------------------------ |
| [Assets](https://app.usehindsight.com/assets) | Your content and competitive materials | Drive, Notion, Confluence, or native |
| [Intel](https://app.usehindsight.com/intel) | Public web data about competitors | URLs, tracked pages |
| Tag: Competitor name | Anything about that competitor | Either section |
| Tag: "You" | Your own playbooks, messaging, positioning | Either section |
# Sales Plays
Source: https://docs.usehindsight.com/guides/plays
Proactive guidance to help reps win deals.
**Plays is in preview.** The capability is rolling out to workspaces — setup steps and screens may change as it reaches general availability.
**Plays** turns the signals in your Deal Reviews into proactive, account-specific guidance for reps. Define the deal conditions that matter, then Hindsight identifies matching opportunities and delivers the next best action, grounded in the deal's evidence.
Use Plays throughout the revenue lifecycle: help a rep prepare for a competitor entering an in-progress opportunity, address a new risk before a key meeting, guide an expansion motion, or re-engage a deal that went cold. Win-backs are one useful play type—not the only one.
Plays sit on top of your [Deal Reviews](/deals-quickstart). The verified record, CRM data, deal evidence, and scored decision drivers Hindsight has assembled for each opportunity make guidance specific to the account—not a generic sequence or static alert.
![Plays overview]()
***
## What a Play is
A Play is a reusable, proactive guidance motion defined by two things:
* **Enrollment criteria** — filters over your deals and their Deal Review fields. A matching deal can enroll automatically when its insights refresh, or you can enroll selected deals manually. For example:
> **Auto-enroll deals where**
> a competitor is present **and** the deal is in evaluation **and** product fit is below the team's target
* **Play guidance** — instructions for the action Hindsight should recommend to the rep. For example: *"Review the competitive risk, cite the most relevant evidence, and prepare a call plan for the account owner."*
You can also attach playbooks, messaging decks, battlecards, and other Asset Library documents. Hindsight uses them as reference material when it creates the guidance.
Because enrollment runs from the deal record, each play is a live list of opportunities where your team can act—not a static report.
![Defining a play's enrollment criteria and motion]()
***
## Set up a Play
Use deal filters to describe the moment this play should address. Combine CRM fields with Hindsight's Deal Review signals—such as stage, competitor, product fit, customer fit, and decision drivers—to target in-progress deals as well as closed-won, closed-lost, or expansion opportunities. For example: *deals in late-stage evaluation with a newly identified competitor*, *accounts ready for expansion*, or *high-fit opportunities lost to sales execution*.
Write clear Play guidance that tells Hindsight the desired outcome, format, and action. For every enrolled opportunity, Paige researches the deal and produces a **recommended play** from its evidence, comparable signals, and your instructions. That could be a call plan, risk response, internal coaching brief, stakeholder strategy, or outreach—not just a win-back message.
Link Asset Library documents that should inform the recommendation: battlecards, playbooks, one-pagers, messaging decks, or product updates. Their content is included when Paige drafts guidance for this play.
Choose whether to notify the deal owner, additional teammates, or both. When an opportunity enrolls, the recipients receive the evidence-led Play in Slack, with options to ask Paige for help, open the associated Hindsight research session, or snooze it. Email notifications can also alert recipients to a new Play.
***
## Track outcomes
Each play tracks the opportunities enrolled in it and their progress—from **pending** and **surfaced** to **engaged**, **snoozed**, **dismissed**, or **converted**. Use that view to see which proactive motions create engagement and where to refine your criteria or guidance.
***
## What's Next
Plays run on your Deal Reviews—make sure your active and closed deals are analyzed and scored.
Use Hindsight Skills and Claude Skills to investigate deal patterns and create supporting enablement at scale.
# Skills and Workflows
Source: https://docs.usehindsight.com/guides/recipes
Build Hindsight skills and schedule recurring prompts for your team
Skills turn a useful set of AI instructions into a reusable capability. In Hindsight, they run in the web interface, through the Responses API, or in Slack. Workflows run a prompt on a schedule, so recurring intelligence reaches the right people without someone having to remember to ask for it.
The two work well together, but they are independent:
| | Skills | Workflows |
| -------------- | -------------------------------------------------------------------- | --------------------------------------- |
| Purpose | Reusable instructions for a specific job | A scheduled prompt that runs repeatedly |
| How it runs | On demand, when selected by name or loaded dynamically when relevant | Automatically on the cadence you choose |
| Where it works | Hindsight’s web interface, Responses API, and Slack | Hindsight |
| Relationship | Can be used in a workflow | May use a skill, but does not need to |
## Default Agent Skills
Hindsight’s Agent has four built-in skills for common research and analysis tasks. These procedures are available by default: the Agent can load the relevant one dynamically, or you can select it by name when you want to direct the work in Hindsight.
* **Competitive enablement** — Researches competitor positioning and creates evidence-backed battlecards, talk tracks, and seller-safe responses.
* **Research Hindsight deals** — Finds relevant historical deals, validates themes against source documents, and returns cited win/loss evidence.
* **Prepare deal strategy** — Builds an evidence-backed strategy for an active deal using deal context, comparable precedents, competitive research, and buyer signals.
* **Analyze Hindsight datasets** — Performs quantitative analysis of Deal Grid data, including win/loss rates, trends, cohorts, and breakdowns.
These defaults provide a reliable starting procedure for common work. Add your own skills when your team has specialized processes, terminology, quality requirements, or output formats that the defaults do not cover.
## Build a Skill
A skill is a concise set of instructions that tells Hindsight’s Agent how to complete one well-defined task. It can include the goal, the context to use, the steps to follow, quality checks, and the format of the final output.
In Hindsight, a skill can be selected by name or loaded dynamically when it matches the task at hand. It is not automatically available to Claude, ChatGPT, or another AI tool.
You can still create skills in Claude or ChatGPT, or export a Hindsight skill for use there. Skills are ultimately Markdown instructions, so you can copy the relevant text between tools. When moving a skill out of Hindsight, adapt any Hindsight-specific tool references or company context to the tools and data available in the destination.
### Start with one job
Give each skill a narrow, recognizable responsibility. Good examples include:
* Summarize new competitive mentions from this week’s calls
* Prepare a win/loss readout for a quarterly review
* Create an account-specific deal strategy from the latest activity
* Turn buyer feedback into product requests and supporting evidence
Avoid combining unrelated jobs into one skill. A focused skill is easier to select, evaluate, and improve.
### Use this structure
Use the following pattern when authoring a skill:
```text theme={null}
# [Skill name]
## Goal
Describe the single outcome this skill should produce.
## When to use it
State the request, signal, or situation that should select this skill.
## Inputs and context
List the Hindsight tools, knowledge-base files, company context, and assumptions to use or avoid.
## Instructions
1. Research or gather the needed evidence.
2. Analyze it using the criteria that matter.
3. Produce the requested output.
## Quality bar
Specify what a good answer includes, such as evidence, caveats, and next steps.
## Output format
Define the headings, table, bullets, or other final structure.
```
### Make skills easy to select
Name skills after the outcome they create, not a vague category. For example, use **Prepare Deal Strategy** instead of **Sales Helper**, or **Weekly Competitor Brief** instead of **Competitive Intelligence**.
Include a short “When to use it” section with the phrases and scenarios that should trigger it. This helps people select a skill by name and helps AI tools load it dynamically when the request fits.
### Give Hindsight the context it needs
Skills are optional, but they give you control over the context and conventions Hindsight should apply. Use them to document information that may not be obvious from an individual request, including:
* When your fiscal quarters start and end
* The currency and reporting conventions your team uses
* The deal fields, segments, and taxonomies that matter for analysis
* The definitions of stages, customer tiers, regions, or other company-specific terms
* The knowledge-base files to use for approved messaging, enablement, or seller guidance
You can also name the specific Hindsight tools the Agent should use. For example, an enablement skill can instruct the Agent to consult a particular knowledge-base file before producing a seller-facing talk track, while an analysis skill can require a particular set of fields for every segmentation.
### Test and improve
Run the skill against a few representative requests before sharing it. Check that it:
* Uses the right source material
* Produces specific conclusions rather than generic summaries
* Separates evidence from assumptions
* Follows the requested format every time
If the output is inconsistent, tighten the instructions or add an example of the expected result. Keep the skill’s instructions self-contained rather than relying on undocumented team knowledge.
If a skill depends on Hindsight data, say which tools, fields, taxonomy, or knowledge-base files to use. This makes the output more consistent and gives the Agent the context it needs to follow your team’s process.
## Create and customize skills in Hindsight
Go to **Skills** (`/skills`) to manage the skills available to your workspace. The page has three libraries:
* **Hindsight-created** — Skill templates provided by Hindsight.
* **Your organization** — Skills teammates have created or added for the workspace.
* **Yours** — Skills you created or added yourself.
### Create a skill from scratch
1. Select **Create skill** on the Skills page.
2. Add a descriptive name, a short description, category, and the skill prompt.
3. Include the goal, relevant Hindsight tools and company context, procedure, quality bar, and output format described above.
4. Select **Create Skill**, then test it in Chat or add it to a workflow.
### Add a Hindsight skill to your library
1. On **Skills**, open the **Hindsight-created** tab.
2. Open a template skill and select **Add Skill**.
3. The copied skill appears in **Yours**, where it is available in your workspace’s skill selectors.
4. Open the copy and select **Edit** to customize its name, description, prompt, and category.
Adding a template creates a copy rather than changing Hindsight’s original. Your customizations affect your workspace’s version only. You can also remix a teammate’s organization skill to make your own editable copy.
If a skill is already used in a workflow, remix it before changing it. This preserves the existing workflow and gives you a safe version to customize.
## Create a Workflow
Use a workflow for work that should happen on a recurring schedule: a weekly brief, monthly trend report, regular competitive monitoring, or a periodic update to a team asset.
A workflow is a scheduled prompt. It can contain all the instructions it needs directly, or it can call on a skill for a reusable part of the work.
### Set up the prompt
1. Go to **Workflows** in Hindsight and select **Create Workflow**.
2. Give the workflow a clear name that describes its recurring outcome.
3. Write the prompt that should run each time.
4. Optionally use **Browse Skills** to add a skill inline, or write the workflow prompt directly.
5. Test the prompt and refine the expected output before scheduling it.
The workflow owns its prompt. Adding a skill brings the relevant instructions into that prompt, so a workflow can also stand alone without a linked skill.
### Choose a cadence and destination
Select the schedule that matches how quickly the information changes—such as daily, weekly, monthly, or a custom cadence. Then choose where the result should go:
* Slack channel or direct message
* Email recipients
* A new or updated asset in the Hindsight Library
* Zapier, for follow-on actions in other tools
### Recurring workflow ideas
* **Weekly competitor brief:** Review recent calls and surface competitor mentions, objections, and suggested response updates.
* **Monthly win/loss report:** Identify recurring reasons deals were won or lost, with supporting examples and recommended actions.
* **Pipeline risk digest:** Summarize open-deal risks, missing next steps, and accounts that need attention.
* **Product feedback roundup:** Group recent buyer feedback into themes, feature requests, and evidence for the product team.
## Use skills outside Hindsight
Hindsight skills run only in Hindsight’s web interface, Responses API, and Slack. To use the same procedure in Claude, ChatGPT, or another AI tool, export or copy the Markdown instructions and add them to that tool’s skill or project setup.
Review the exported instructions before using them elsewhere. Replace Hindsight tool names with the destination tool’s capabilities, and provide any necessary company schema, taxonomy, or source documents that would otherwise have been available in Hindsight.
## When to use which
Use a **skill** when someone needs to run a repeatable task on demand, or when you want an AI tool to recognize and apply specialized instructions. Use a **workflow** when the task should run without manual effort on a schedule. Combine them when a recurring workflow benefits from a tested, reusable skill—but do not create a skill solely because a workflow needs a prompt.
## Best practices
* Keep the task and output specific.
* Give skills descriptive names and clear selection cues.
* Ask for source-backed findings and call out uncertainty.
* Review early workflow runs before relying on automated delivery.
* Revisit prompts and skills as your data, process, or priorities change.
# Hindsight API
Source: https://docs.usehindsight.com/integrations/api
Integrate Hindsight intelligence into your AI agents, MCP servers, and custom applications
## Overview
The Hindsight API provides access to competitive intelligence, win-loss insights, and deal data through two integration methods:
1. **REST API** - either receive a complete, cited AI response or call supported Hindsight tools directly
2. **[Model Context Protocol (MCP)](/integrations/mcp)** - Individual tools your AI assistant orchestrates directly
This page covers the REST API. Direct REST tool calls and MCP calls use the same authorization, validation, limits, and underlying tool execution.
### When to Use Each
* **REST API responses**: For Glean, Slack bots, and search interfaces that want a finished, synthesized answer
* **REST API tools**: For server-side applications that need structured search or retrieval results without an LLM-generated response
* **[MCP](/integrations/mcp)**: For Claude, ChatGPT, Cursor, or other MCP clients that orchestrate tools themselves
***
## API keys
All API requests require an API key in the `Authorization` header:
```yaml theme={null}
Authorization: Bearer YOUR_API_KEY
```
Create API keys in **Hindsight Settings → API keys**. The plaintext key is shown only once, at creation. Store it in a secrets manager; Hindsight cannot display it again.
Newly created API keys begin with `hs_`. Existing keys remain supported until they are rotated or expire.
Each key is tied to the organization in which it was created, its creator's current organization role, its explicit API-key scopes, and an optional expiry date. A key is rejected immediately when it is revoked, expires, or its creator is no longer a member of that organization.
Scopes can only reduce access. They never grant access beyond the creator's current role or the organization's configured MCP/API permissions.
### Available scopes
| Scope | Allows |
| ------------------------ | ------------------------------------------------------------------ |
| `deals:read` | Read deals, deal schema, datasets, and comparable-deal data |
| `documents:read` | Search and retrieve deal documents |
| `competitive_intel:read` | Search competitive assets/intel and use related web research tools |
| `knowledge_base:read` | Search company messaging and knowledge-base documents |
| `exports:read` | Create, inspect, and download deal exports |
| `responses:execute` | Use the Responses API |
| `documents:write` | Upload documents to deals |
| `knowledge_base:write` | Upload knowledge-base documents and competitive intelligence |
| `interviews:write` | Create and update interview requests |
| `workflows:read` | Read workflow metadata |
| `workflows:write` | Create, update, or delete workflows |
### Read-only integrations
For competitive discovery, narrative generation, analytics, or reporting, create a key with only the required read scopes. Do not grant any `*:write` scope unless the integration must change Hindsight data.
Recommended default read-only scopes:
* `deals:read`
* `documents:read`
* `competitive_intel:read`
* `knowledge_base:read`
Add `exports:read` only when the integration needs downloadable deal exports. Add `responses:execute` only when the integration invokes the Hindsight Responses API.
### Expiration and rotation
Available lifetimes are 7 days, 30 days, 90 days, 1 year, and Never. The default is 30 days.
Create a replacement key before the old key expires, update the external integration, verify it works, then revoke the old key. Revocation takes effect immediately.
Existing keys have a 90-day transition expiry after this feature is deployed and should be rotated before then. Reserve indefinite keys for managed, long-lived integrations and review them regularly.
![API Keys]()
***
## REST API
The REST API has two surfaces. Use **Responses** when you want Hindsight's AI to orchestrate multiple searches and return a synthesized, cited answer. Use **Tools** when your application needs structured results and controls the workflow itself.
**Best for:** Glean, Slack bots, search interfaces, custom applications
### Endpoint
```
POST https://app.usehindsight.com/api/v1/responses
```
### Request Format
```json theme={null}
{
"messages": [
{
"role": "user",
"content": "What security objections have we encountered with Enterprise customers?"
}
],
"stream": false
}
```
### Response Format
```json theme={null}
{
"message": {
"role": "assistant",
"content": "Based on security discussions in enterprise deals, here are the main objections:\n\n1. **Data Encryption** - Multiple customers asked about encryption at rest and in transit [Acme Corp Deal](https://app.usehindsight.com/deals/abc123), [TechCo Deal](https://app.usehindsight.com/deals/def456)\n\n2. **Compliance Certifications** - SOC2 and ISO 27001 certifications were requested in 8 deals [Enterprise RFP Analysis](https://app.usehindsight.com/docs/xyz789)...",
"citations": [
{
"document_id": "doc_abc123",
"document_name": "Acme Corp - Security Requirements.pdf",
"deal_id": "deal_abc123",
"deal_name": "Acme Corp Deal",
"url": "https://app.usehindsight.com/deals/abc123/documents/doc_abc123",
"excerpt": "Customer requires end-to-end encryption for all data..."
}
]
},
"tool_calls": [
"search_across_deals",
"search_deal_documents"
]
}
```
### Streaming Support
Enable streaming for real-time responses:
```json theme={null}
{
"messages": [...],
"stream": true
}
```
Stream format follows SSE (Server-Sent Events):
```
data: {"content": "Based on security", "type": "content_delta"}
data: {"content": " discussions", "type": "content_delta"}
data: {"citation": {...}, "type": "citation"}
```
***
## Direct Tool API
Direct tool endpoints accept JSON input and return structured JSON. They are useful when you know the retrieval step you need and want to compose the workflow in your own service.
The recommended deal-research flow is:
1. Call [`select-deal`](/api-reference/select-deal) to filter and triage analyzed deals.
2. Pass the returned `deal_id` values to [`get-deal`](/api-reference/get-deal) for summaries and competitor positioning.
| Endpoint | Use it for |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [`POST /tools/select-deal`](/api-reference/select-deal) | Finding analyzed deals by name, competitor, stage, amount, date, owner, and other filters. Returns lean, paginated rows. |
| [`POST /tools/get-deal`](/api-reference/get-deal) | Getting full details for one to ten known deal IDs. |
See the [Direct Tool API reference](/api-reference/tools) for the complete list of available deal research, competitive intelligence, web research, and data-analysis tools.
For a client-side AI assistant that should choose and sequence tools itself, use [MCP](/integrations/mcp) instead.
***
## Document Upload API
Upload documents to your Hindsight knowledge base or associate them with specific deals.
### Upload to Knowledge Base
Upload competitive intelligence documents, assets, and other files to your library.
```
POST https://app.usehindsight.com/api/v1/documents/library
```
#### Request Format
Send as `multipart/form-data`:
```
file_name=Competitor X Pricing Guide.pdf
file_url=https://example.com/document.pdf
content_type=application/pdf
type=asset
competitor_id=comp_123
source=drive
```
#### Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `file_name` | string | Yes | Name of the file |
| `file_url` | string | Yes\* | URL to download the file from |
| `file` | binary | Yes\* | Binary file content (alternative to `file_url`) |
| `content_type` | string | Yes | MIME type (e.g., `application/pdf`, `text/markdown`) |
| `type` | string | Yes | Document type: `"asset"` or `"intel"` |
| `competitor_id` | string | Yes\*\* | Hindsight competitor ID |
| `competitor_name` | string | Yes\*\* | Competitor name (resolved to ID automatically) |
| `source` | string | No | Source application: `"drive"`, `"notion"`, `"confluence"`, `"onedrive"`, `"sharepoint"`, `"vanta"`, `"url"`, `"zapier"`, `"api"` |
\*Either `file_url` or `file` is required\
\*\*Either `competitor_id` or `competitor_name` is required
#### Response
```json theme={null}
{
"document": {
"id": "doc_abc123",
"file_name": "Competitor X Pricing Guide.pdf",
"status": "processing",
"url": "https://app.usehindsight.com/documents/viewer/[doc_id]",
"created_at": "2026-02-10T12:00:00Z"
},
"run_id": "run_xyz789"
}
```
***
### Upload to Deal
Associate documents with specific deals for win-loss analysis.
```
POST https://app.usehindsight.com/api/v1/deals/documents
```
#### Request Format
Send as `multipart/form-data`:
```
file_name=Discovery Call Notes.pdf
file_url=https://example.com/document.pdf
content_type=application/pdf
deal_id=deal_123
source=gong
```
#### Parameters
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `file_name` | string | Yes | Name of the file |
| `file_url` | string | Yes\* | URL to download the file from |
| `file` | binary | Yes\* | Binary file content (alternative to `file_url`) |
| `content_type` | string | Yes | MIME type (e.g., `application/pdf`, `audio/mpeg`) |
| `deal_id` | string | Yes\*\* | Hindsight deal ID |
| `salesforce_id` | string | Yes\*\* | Salesforce Opportunity ID |
| `hubspot_id` | string | Yes\*\* | HubSpot Deal ID |
| `source` | string | No | Source application: `"gong"`, `"clari"`, `"fathom"`, `"fireflies"`, `"avoma"`, `"outreach"`, `"gmail"`, `"Salesforce"`, `"Hubspot"`, `"api"` |
\*Either `file_url` or `file` is required\
\*\*One of `deal_id`, `salesforce_id`, or `hubspot_id` is required
#### Supported File Types
* **Documents**: PDF, Word, PowerPoint, Excel, Markdown, plain text
* **Audio**: MP3, WAV, M4A (automatically transcribed)
* **Video**: MP4 (automatically transcribed)
#### Response
```json theme={null}
{
"document": {
"id": "doc_def456",
"file_name": "Discovery Call Notes.pdf",
"status": "processing",
"deal_id": "deal_123",
"url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_def456",
"created_at": "2026-02-10T12:00:00Z"
},
"run_id": "run_abc123"
}
```
### Example Usage
Once configured, you can ask Claude questions like:
* "Find deals where we lost to Competitor X in the last quarter"
* "What are the top security objections we've encountered?"
* "Search for pricing discussions in enterprise deals"
* "Show me competitor intel on Salesforce's integration strategy"
Claude will automatically call the appropriate Hindsight tools and synthesize the results
***
## Common Use Cases
### Use Case 1: Glean Integration
Integrate Hindsight as a data source in Glean to answer competitive intelligence and win-loss questions.
**REST API Example:**
```bash theme={null}
curl -X POST https://app.usehindsight.com/api/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "What are common objections to our enterprise tier?"}]
}'
```
**Best for:** When you want comprehensive, cited answers in Glean search results.
***
### Use Case 2: Claude Desktop for Sales Prep
Use Claude with Hindsight tools to prepare for sales calls, analyze deals, and get competitive intel.
**Example Conversation:**
```
You: "I have a call with a prospect considering Salesforce. Help me prepare."
Claude: [Uses search_competitive_intel and search_across_deals tools]
"Here's what I found about competing with Salesforce..."
```
**Best for:** Sales reps preparing for calls, analyzing win/loss patterns, researching competitors.
***
### Use Case 3: Custom Slack Bot
Build a Slack bot that answers team questions about deals and competitors.
**REST API Example:**
```javascript theme={null}
app.message(async ({ message, say }) => {
const response = await fetch('https://app.usehindsight.com/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
messages: [{ role: 'user', content: message.text }]
})
});
const data = await response.json();
await say(data.message.content);
});
```
**Best for:** Team-wide access to competitive intelligence and deal insights.
***
## Rate limits
Hindsight applies both organization-wide and per-API-key request limits. The organization-wide limit protects overall platform capacity, while the per-key limit prevents one compromised or malfunctioning key from exhausting the organization's entire allowance.
Per-key defaults are derived from the organization's plan limit: approximately one-third of the organization limit, with a minimum of 5 requests per minute. Expensive operations such as exports, uploads, interview actions, and AI/Responses requests may also consume separate usage quotas.
Clients should handle `429 Too Many Requests` using these existing response headers:
| Header | Meaning |
| ----------------------- | ------------------------------------------------------------------------ |
| `X-RateLimit-Limit` | Requests allowed in the active response limit window. |
| `X-RateLimit-Remaining` | Requests remaining in that window. |
| `X-RateLimit-Reset` | Unix timestamp in milliseconds when the active rate-limit window resets. |
Do not infer separate per-key response headers: the current public headers represent the active response limit.
***
## Error Handling
All errors follow this format:
```json theme={null}
{
"error": {
"code": "unauthorized",
"message": "Invalid API key",
"details": {}
}
}
```
When a key does not include the scope required for an action:
```json theme={null}
{
"error": {
"code": "insufficient_scope",
"message": "This API key is not scoped for this action.",
"required_scopes": ["documents:write"]
}
}
```
When the creator's role does not allow the action:
```json theme={null}
{
"error": {
"code": "forbidden",
"message": "Your role (member) does not have permission to perform this action."
}
}
```
For an invalid, expired, revoked, or otherwise unusable key:
```json theme={null}
{
"error": {
"code": "unauthorized",
"message": "Invalid API key"
}
}
```
### Error Codes
* `400` - Bad Request (invalid parameters)
* `401` - Unauthorized (invalid API key)
* `403` - Forbidden (insufficient scope or permissions)
* `404` - Not Found (resource doesn't exist)
* `429` - Too Many Requests (rate limit or applicable usage quota exceeded)
* `500` - Internal Server Error
***
## Next Steps
Generate your API key from the dashboard
Detailed MCP configuration and the full tool reference
Full reference for the responses endpoint
Browse every structured-search and analysis tool
How the verified deal layer is built
# Gong Integration
Source: https://docs.usehindsight.com/integrations/gong
Connect Gong to Hindsight
### Overview
Hindsight integrates with Gong to extract Competitive Win-Loss Insights from your calls with prospects.
These insights are then used in battlecards, reports, and more.
![Deal Insights]()
### Getting Started
![Gong]()
1. Go to the [Integrations](https://app.usehindsight.com/settings/integrations) page in Hindsight.
2. Connect Gong to Hindsight by clicking the "Connect" button.
3. Sign into Gong and authorize Hindsight to access your Gong data.
That's it!
### How it Works
![Deal Home]()
1. When Deals are imported to Hindsight (usually via Salesforce or HubSpot integration), Hindsight will find the matching calls in Gong and import them to the right deal.
2. This relies on the integration between Gong and your CRM for matching, and as a fallback, the contact's email.
3. Hindsight will then analyze the calls and extract Competitive Win-Loss Insights using AI.
4. These insights are then used to update your Competitive Intelligence database, and can be used in battlecards, reports, and more.
# HubSpot Integration
Source: https://docs.usehindsight.com/integrations/hubspot-integration
Sync Hindsight with HubSpot for Deal Analysis
## Overview
Hindsight connects to HubSpot via OAuth to sync your deals and analyze them for competitive win-loss insights. This guide will help you set up the integration and start using it effectively.
![Dashboard]()
For support, please reach out via your Slack Connect channel or via [email](mailto:support@usehindsight.com)
### How it Works
When you connect Hindsight to your HubSpot CRM, you'll be able to **import specific Deals into Hindsight**. Hindsight will analyze these Deals to extract competitive insights based on your decision drivers.
You can set up **automation rules** in Hindsight that automatically import Deals based on custom criteria. You can use your HubSpot data to **filter in the Win-Loss dashboard** and analyze your Deals based on specific criteria, such as stage, amount, or close date.
![integrations]()
### Daily Sync
**Opportunties are synced for the latest data every 12 hours**. This means that any changes made to your Deals in HubSpot will be reflected in Hindsight automatically.
Hindsight listens to Deals via webhooks to make this seamless for users.
### Supported Objects
Hindsight only syncs objects associated with the Deals that you import. This includes:
* Deals
* Account
* Products
* Contacts
* Custom Fields
* Notes
* Emails
* Meetings
* Tickets
![hubspot deal]()
### Segments
**You can configure [segments](https://app.usehindsight.com/settings/segments) in Hindsight to filter your Deals based on custom criteria.** This allows you to analyze specific subsets of your Deals, such as those with a certain stage, amount, or close date.
Segments are useful for analyzing your Deals based on specific criteria, such as:
* Deals with a certain stage or pipeline (e.g. "Closed Won, New Business")
* Deals with a certain amount (e.g. "> \$10,000")
* Deals with a certain close date (e.g. "Next 30 days")
* Deals with a certain account type (e.g. "Enterprise")
* Deals with a certain product (e.g. "Product A")
* Deals with a certain region (e.g. "North America")
![slack deal]()
## Connecting HubSpot
### Authorization
**Authorizing HubSpot requires admin access to your HubSpot account.** Click "Connect" on the [integrations](https://app.usehindsight.com/settings/integrations) page and follow the authorization steps.
This will redirect you to the HubSpot authorization page. Click "Allow" to authorize Hindsight to access your HubSpot account. If you're having issues, contact your HubSpot admin.
![slack deal]()
### Import Rules
Setting up import rules allows you to **automatically import Deals into Hindsight** based on custom criteria. This is useful for keeping Hindsight's insights up-to-date without manual intervention.
We recommend filtering to Closed Won and Lost Deals. You can also filter by custom fields, such as "Region" or "Product", to analyze specific subsets of your Deals.
![slack deal]()
## Customization
### Deals Stages
To help Hindsight understand your custom Deals stages, navigate to the [CRM Settings](https://app.usehindsight.com/settings/properties) and click the "Stages" tab.
**Mark your custom Deals stages as "Closed Won" or "Closed Lost"** to help Hindsight analyze your Deals correctly. This will allow Hindsight to tag your Deals with the correct status and provide accurate win-loss insights.
![slack deal]()
### Custom Properties
You can customize the properties that Hindsight uses to analyze your Deals in [CRM Settings](https://app.usehindsight.com/settings/properties) on the "Deals" and "Accounts". Having more properties makes analysis and sync slower, so "turn off"
You can map your custom properties to Hindsight's default properties like "Region", "Type", and "Amount". Properties that are "Synced" but not mapped to a Hindsight property will still be analyzed and available for filtering.
![slack deal]()
### Line Items
Hindsight pulls in your [line items](https://app.usehindsight.com/settings/products) from HubSpot to analyze your Deals. This allows Hindsight to provide insights on specific products and services associated with your Deals.
![slack deal]()
# Hindsight MCP
Source: https://docs.usehindsight.com/integrations/mcp
Connect AI assistants to your Hindsight deal data via the Model Context Protocol
## Model Context Protocol (MCP) Integration
Hindsight exposes its AI agent capabilities through the Model Context Protocol (MCP), allowing AI assistants to directly query your deal data, research competitors, and analyze pipeline metrics.
**Compatible with:** Claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, Cline, and any MCP-compatible client.
***
## Setup
### Connect via Claude.ai
The easiest way to connect Hindsight is directly through the Claude.ai web app with no API keys or config files required.
**1. Open the sidebar customization panel**
Click the customize button in the Claude sidebar on the left.
![Open the Claude sidebar]()
**2. Open Connectors**
Click the **Connectors** button in the panel that appears.
![Click Connectors]()
**3. Add a new connector**
Click the **+** button to add a custom connector.
![Click the plus button]()
**4. Fill in the Hindsight connector details**
Set the name to `Hindsight` and the URL to `https://app.usehindsight.com/api/mcp`, then click **Add**.
![Fill in connector details]()
**5. Connect**
Click **Connect** on the Hindsight connector. If your account belongs to multiple Hindsight organizations, you'll be prompted to select which org to associate with this connection.
![Click Connect]()
That's it — Hindsight is now available in your Claude.ai conversations.
The one-click `hindsight.mcpb` bundle install is deprecated. Connect via HTTP instead by adding Hindsight directly to your Claude Desktop config file:
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"hindsight": {
"type": "http",
"url": "https://app.usehindsight.com/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Restart Claude Desktop after saving. Generate an API key from **Settings → API Keys** in the Hindsight app.
### Claude Code
Run this command in your terminal:
```bash theme={null}
claude mcp add hindsight --transport http https://app.usehindsight.com/api/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
```
Generate an API key from **Settings → API Keys** in the Hindsight app.
### ChatGPT Developer Mode
ChatGPT's MCP support is available in beta via **Developer Mode** on Pro, Plus, Business, Enterprise, and Education accounts.
**1. Enable Developer Mode**
Go to **Settings → Apps → Advanced settings → Developer mode** and toggle it on.
**2. Create a Hindsight app**
1. Open **ChatGPT Apps settings**
2. Click **Create app** (only visible when Developer Mode is enabled)
3. Enter `https://app.usehindsight.com/api/mcp` as the MCP server URL
4. Set authentication to "OAuth"
5. After hitting "Create" you should be directed to a new page to login with your Hindsight account to authenticate
The app will appear under **Drafts** in your app settings.
**3. Use Hindsight in a conversation**
Select **Developer Mode** from the composer's Plus menu, choose the Hindsight app, and start your conversation. For best results, be explicit about which tool to use:
> "Use the Hindsight app's `search_across_deals` tool to find why we lost deals to Salesforce last quarter."
For more details, see [OpenAI's Developer Mode documentation](https://developers.openai.com/api/docs/guides/developer-mode).
### HTTP / JSON-RPC
The Hindsight MCP server is a standard HTTP endpoint. Any HTTP client can call it directly using JSON-RPC 2.0.
**Endpoint:** `https://app.usehindsight.com/api/mcp`
**Required headers:**
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json, text/event-stream
```
**List available tools:**
```bash theme={null}
curl -X POST https://app.usehindsight.com/api/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
**Call a tool:**
```bash theme={null}
curl -X POST https://app.usehindsight.com/api/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "fetch_hindsight_context",
"arguments": {}
}
}'
```
Each tool's exact arguments are returned by `tools/list` above. `fetch_hindsight_context` takes no arguments and is the usual starting point — it returns the competitors and deal stages the other tools reference. This approach works with any language or framework — no MCP client library required.
***
## Reconnecting after an update
Hindsight MCP moved to OAuth sign-in in [MCP 2.0](/release-notes/mcp-2.0). If you connected against the older preview server, the old connection won't authenticate anymore — you need to reconnect once against the current server. A stale connection typically shows up as a login loop, a `401`/`invalid_token` error, or tools that silently return nothing.
Claude has no in-place "reauthenticate" button for a custom connector. To re-sign-in you **remove the old connector and add it again** — editing an existing connector isn't supported. Reconnecting is safe: it doesn't touch your Hindsight data, only the local credential.
**1. Remove the old connector**
Go to **Customize → Connectors**, find the old **Hindsight** entry, open the **⋯** menu, and click **Remove**.
**2. Add it again**
Click **+ → Add custom connector**, set the URL to `https://app.usehindsight.com/api/mcp`, and click **Add**.
**3. Connect and sign in**
Click **Connect**. Claude opens your browser to sign in to Hindsight; if you belong to multiple orgs, pick the workspace for this connection.
**4. Re-check tool permissions**
With 2.0's direct tool calls, you control which tools are exposed. After reconnecting, confirm the Hindsight tools you want are enabled in the connector's settings.
Manual setups that use `npx mcp-remote` cache their OAuth tokens on disk, so a fresh sign-in won't happen until you clear that cache. Removing and re-adding the connector in Claude is **not** enough here — clear the cache, then let the flow re-run.
Quit Claude Desktop / your client first, then delete the cache directory:
```bash macOS / Linux theme={null}
rm -rf ~/.mcp-auth
```
```powershell Windows (PowerShell) theme={null}
Remove-Item -Recurse -Force "$env:USERPROFILE\.mcp-auth"
```
Reopen your client — the next call runs the full OAuth flow and stores fresh tokens.
If your manual config uses an **API key** (`Authorization: Bearer YOUR_API_KEY`) rather than OAuth, there's nothing to reauthenticate — just confirm the key is still valid under **Settings → API Keys** in Hindsight and that your config points at `https://app.usehindsight.com/api/mcp`.
***
## Team & Enterprise workspaces
On Claude **Team** and **Enterprise** plans, individual members usually **cannot** add a custom connector themselves — an **Owner** (or Primary Owner) has to approve it for the organization first. If you don't see an **Add custom connector** option, this is why.
In Claude, go to **Organization settings → Connectors → Add**, hover **Custom**, and choose **Web**. Enter the URL `https://app.usehindsight.com/api/mcp` and click **Add**. (Leave **Advanced settings** / OAuth Client ID & Secret blank — Hindsight's OAuth is handled per user at connect time.)
Once the Owner has added it, each member goes to **Customize → Connectors**, finds the **Hindsight** entry (marked with a **Custom** label), and clicks **Connect** to run their own OAuth sign-in and pick their workspace.
Access stays **per user**, not shared. Each member signs in as themselves and only sees the Hindsight org they select — the Owner enabling the connector doesn't grant anyone access to Hindsight data. See the [MCP 2.0 notes](/release-notes/mcp-2.0#oauth-is-now-the-primary-sign-in).
If your organization is on a plan where a member added a preview-era connector before Owner approval was required, that member should **remove** it (**Customize → Connectors → ⋯ → Remove**) and reconnect to the Owner-approved one so everyone is on the same server.
For the authoritative admin steps, see Anthropic's guides on [getting started with custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) and [using connectors](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities).
***
## Available Tools
The server exposes the verified deal layer as a focused set of tools, grouped below. Most workflows open with **`fetch_hindsight_context`** to learn the workspace's competitors and deal stages, then branch into the relevant group. For the exact current surface — including parameters — call `tools/list` against the endpoint (see the [Direct API](#direct-api) tab above).
### Context & schema
| Tool | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `fetch_hindsight_context` | Fetch competitors and deal stages needed to use the other tools. Usually the first call. |
| `pull_schema` | Fetch the CRM field schema for your workspace — field names and types for the deal grid. Use before `create_dataset`. |
### Deals & pipeline
| Tool | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `select_deal` | Filter and list deals by criteria (competitor, stage, amount, date, owner, and more). Pass a conceptual `semantic_query` to rank matches by similarity to a description instead of paging by date. Returns lean rows for fast triage. |
| `get_deal` | Get full details for specific deals by ID. |
| `search_comparable_deals` | Find the most comparable historical deals for a source deal, including each matching dimension and score. |
| `search_across_deals` | Search all deal documents across the entire pipeline. |
| `search_deal_documents` | Deep search within specific deals. |
| `pull_full_document` | Fetch full document content by ID when retrieved chunks aren't enough. |
### Competitive intelligence
| Tool | Description |
| --------------------------- | ------------------------------------------ |
| `search_competitive_assets` | Search battlecards and competitive assets. |
| `search_competitive_intel` | Search pre-saved competitive intelligence. |
### Knowledge base
| Tool | Description |
| ----------------------- | ----------------------------------------------------------------- |
| `search_knowledge_base` | Search your company's messaging docs, playbooks, and positioning. |
### Live web research
| Tool | Description |
| --------------- | ---------------------------------------------------- |
| `search_web` | Live web search for competitive and market research. |
| `scrape_url` | Extract content from a specific URL. |
| `map_site_urls` | Discover and map the structure of a website. |
### Quantitative analysis
For win-rate, trend, and segment questions over the deal grid.
| Tool | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_dataset` | Build a structured dataset from your deal pipeline. |
| `run_sandbox_dataset_analysis` | Run a user-supplied Python script against a dataset from `create_dataset` in an isolated, network-disabled sandbox, printing the requested aggregate or table and optionally saving up to 3 charts. Replaces the retired `analyze_dealgrid_subset`. |
**Typical flow:** `pull_schema` → `create_dataset` → `run_sandbox_dataset_analysis`.
### Write back
| Tool | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `upload_deal_document` | Attach a document to a deal — pass the text directly or a downloadable file URL (PDF, DOCX, audio, video). |
| `upload_to_knowledge_base` | Upload your own company's docs, playbooks, case studies, or approved messaging to the knowledge base. |
| `upload_competitive_intel` | Save competitor pricing, positioning, feature notes, or gathered news to the knowledge base. |
Tool availability is role-based. By default, workspace admins can use every tool; managers can use the read tools plus the data-analysis tools; and members can use the read tools. Workspace admins can customize these permissions in **Settings → MCP Tools**.
***
## How It Works
The tools read from Hindsight's verified deal layer — one cross-referenced record per deal, built server-side by the Analyze Engine. Search and research tools return cited results grounded in your source documents and knowledge base; quantitative tools run structured queries against your exported deal grid and compute the metrics you ask for.
Because retrieval and verification happen up front, your agent orchestrates clean, cited tools rather than re-deriving context from raw transcripts on every call. See the [Platform Overview](/overview) for how the verified layer is built.
***
## Authentication
MCP requests authenticate using your Hindsight API key as a Bearer token. Keys are scoped to your organization — all tools operate on your org's data only.
Generate an API key from **Settings → API Keys** in the Hindsight app.
# Okta SSO
Source: https://docs.usehindsight.com/integrations/okta-sso
Set up SAML Single Sign-On for Hindsight using Okta Workforce
## Overview
Hindsight supports enterprise Single Sign-On (SSO) via SAML 2.0 using Okta Workforce. Once configured, users in your organization can sign in to Hindsight using their existing Okta credentials — no separate password needed.
Setting up Okta SSO is a two-part process:
1. **Your IT admin** configures a SAML app in Okta and sends Hindsight a Metadata URL.
2. **Your Hindsight Success Manager** completes the connection on our side and enables it.
For support, reach out via your Slack Connect channel or [email us](mailto:support@usehindsight.com).
***
## What We Support
| Feature | Supported |
| ----------------------------------------------- | ---------------------------------------------------- |
| SAML 2.0 | ✅ Yes |
| SP-initiated SSO (sign in from Hindsight) | ✅ Yes |
| IdP-initiated SSO (sign in from Okta dashboard) | ✅ Yes |
| Automatic account linking for existing users | ✅ Yes |
| Multiple email domains per connection | ❌ No — one domain per connection |
| Subdomain matching (e.g. `sales.company.com`) | ⚠️ Available on request |
| SCIM provisioning / automatic deprovisioning | ❌ Not supported — user assignment is managed in Okta |
| Multi-factor authentication (MFA) passthrough | ✅ Yes — Okta MFA is respected |
| OIDC / OAuth SSO | ❌ Not supported for Okta — SAML only |
If you need subdomain support (e.g. users with `@sales.company.com` logging in under a `company.com` connection), let your Success Manager know before setup begins.
***
## What You'll Need
Before starting, make sure you have:
* **Admin access** to your Okta account
* The **email domain** your users will sign in with (e.g. `company.com`)
* Two values that Hindsight will provide to you:
* **Single Sign-On URL** (also called the ACS URL)
* **Audience URI** (also called the SP Entity ID)
Your Hindsight Success Manager will send these to you before you begin.
***
## Setup Instructions (For Your Okta Admin)
### Step 1: Create a new SAML app integration in Okta
1. Sign in to [Okta](https://www.okta.com/) and go to the **Admin** dashboard.
2. In the left navigation, go to **Applications → Applications**.
3. Click **Create App Integration**.
4. In the modal, select **SAML 2.0** and click **Next**.
5. Enter an **App name** (e.g. "Hindsight") and click **Next**.
### Step 2: Configure SAML settings
On the **Configure SAML** page:
1. In the **Single sign-on URL** field, paste the value provided by Hindsight.
2. In the **Audience URI (SP Entity ID)** field, paste the value provided by Hindsight.
3. Leave **Name ID format** as `EmailAddress` and **Application username** as `Okta username`.
### Step 3: Set up attribute statements
Hindsight requires the following attributes to be mapped in Okta. These are **the default Okta values** and typically don't need to be changed, but it's worth verifying:
| Name | Value |
| ----------- | ---------------- |
| `mail` | `user.email` |
| `firstName` | `user.firstName` |
| `lastName` | `user.lastName` |
To verify or add these:
1. Scroll to the **Attribute Statements (optional)** section.
2. Add each row from the table above — enter the **Name** and select the corresponding **Value** from the dropdown.
3. Click **Next**, fill out the feedback form as you like, and click **Finish**.
Incorrect attribute mappings are one of the most common causes of SSO errors. Double-check that `mail` maps to `user.email` before proceeding.
### Step 4: Assign users or groups
Before anyone can sign in via Okta SSO, they must be assigned to the app:
1. Go to the **Assignments** tab on your new app.
2. Click **Assign** and choose **Assign to People** or **Assign to Groups**.
3. Search for and assign the relevant users or groups.
4. Click **Done**.
Only users assigned to this Okta app will be able to sign in to Hindsight via SSO. If a user is not assigned, they will not be able to authenticate.
### Step 5: Copy the Metadata URL
Once setup is complete:
1. Go to the **Sign On** tab of your Okta app.
2. Under **Sign on methods**, find and copy the **Metadata URL**.
3. Send this URL to your Hindsight Success Manager.
***
## What Happens Next (Hindsight's Side)
Once your Success Manager receives the Metadata URL, they will:
1. Paste it into the Hindsight/Clerk connection configuration.
2. Verify the connection is set up correctly.
3. Enable the connection for your domain.
Once enabled, **all users with email addresses matching your configured domain will be redirected to Okta** when signing in to Hindsight. Existing Hindsight users with matching email domains will have their accounts automatically linked to SSO.
If there are existing users on your domain and there's a misconfiguration in Okta, those users may be unable to sign in once the connection is enabled. We recommend coordinating with your Success Manager to test at a low-traffic time.
***
## Frequently Asked Questions
**Will existing Hindsight users be affected?**
Yes — any existing user whose email matches your domain will be migrated to SSO automatically. They will be prompted to authenticate through Okta on their next sign-in.
**What if a user is removed from Okta?**
If a user is deprovisioned in Okta (removed or deactivated), they will no longer be able to sign in to Hindsight via SSO. However, their Hindsight account and data are **not automatically deleted**. Contact your Success Manager if you need an account removed.
**Can we use multiple domains?**
Each SSO connection supports one domain. If you have users across multiple domains (e.g. `companya.com` and `companyb.com`), contact your Success Manager to set up separate connections.
**Can users still sign in with a password?**
Once SSO is enabled for your domain, users will be routed through Okta and cannot bypass it with a password. If you need a fallback for specific users, let your Success Manager know.
**Do you support SCIM for automatic provisioning?**
Not currently. User access is managed by assigning or unassigning users in your Okta app. We recommend reviewing assignments before and after employee onboarding/offboarding.
# Outreach Integration
Source: https://docs.usehindsight.com/integrations/outreach-integration
Connect Outreach Kaia to Hindsight via S3 Export
## Overview
Hindsight integrates with Outreach Kaia to extract Competitive Win-Loss Insights from your call recordings and transcripts. Since Outreach doesn't provide direct API access to Kaia transcripts, this integration uses Outreach's daily S3 export feature to securely transfer your call data to Hindsight.
The main steps:
1. Set up an AWS S3 bucket to recieve Outreach Kaia exports (follow this guide)
2. Configure Outreach to export Kaia recordings to your S3 bucket daily [see Outreach docs](https://support.outreach.io/hc/en-us/articles/28005562346395-Exporting-Data-in-Kaia-using-Daily-Export)
3. Connect Hindsight to your Outreach account and S3 bucket using the steps below (detailed instructions follow)
For support, please reach out via your Slack Connect channel or via [email](mailto:support@usehindsight.com)
### How it Works
1. **Daily Export**: Outreach automatically exports your Kaia call recordings and transcripts to your AWS S3 bucket every day
2. **Secure Access**: Hindsight securely accesses your S3 bucket using the credentials you provide
3. **Smart Matching**: Hindsight automatically matches call transcripts to the right deals based on participant emails, account domains, and call timing
4. **AI Analysis**: Hindsight analyzes the call transcripts to extract competitive insights and decision drivers
5. **Deal Integration**: Insights are automatically added to your deals and used in battlecards, reports, and competitive intelligence
## Setup Requirements
### Prerequisites
* **Outreach Admin Access**: You need admin access to configure the daily export feature
* **AWS Account**: You need an AWS account to create the S3 bucket
* **Growth Plan**: Outreach integration requires a Hindsight Enterprise plan
### Setup Overview
This setup involves three main steps:
1. **Create AWS S3 Bucket** - Set up a dedicated bucket for Outreach exports
2. **Configure Outreach Export** - Enable daily export to your S3 bucket
3. **Connect to Hindsight** - Provide S3 credentials to Hindsight
***
## Step 1: Create AWS S3 Bucket
### 1.1 Create the S3 Bucket
1. Log into your [AWS Console](https://console.aws.amazon.com/)
2. Navigate to **S3** service
3. Click **"Create bucket"**
4. Configure your bucket:
* **Bucket name**: `your-company-outreach-kaia` (choose a unique name)
* **AWS Region**: Choose a region close to your location
* **Block Public Access**: Keep all public access blocked (recommended)
* **Bucket Versioning**: Enable (recommended)
* **Default encryption**: Enable with Amazon S3 managed keys (SSE-S3)
5. Click **"Create bucket"**
### 1.2 Create IAM User for Hindsight
1. Navigate to **IAM** service in AWS Console
2. Click **"Users"** in the left sidebar
3. Click **"Create user"**
4. Configure the user:
* **User name**: `hindsight-outreach-access`
* Leave **"Provide user access to the AWS Management Console"** **unchecked** - we only need programmatic access
5. Click **"Next"**
### 1.3 Create and Attach IAM Policy
⚠️ **Important**: The next steps involve creating a policy in a new tab, then returning to attach it. Keep both tabs open!
1. Click **"Attach policies directly"**
2. Click **"Create policy"**
⚠️ **Note**: This opens a new browser tab - **do not close your user creation tab!**
3. **In the new policy tab**, switch to the **JSON** tab
4. **Delete all existing content** and paste this policy:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::your-company-outreach-kaia",
"arn:aws:s3:::your-company-outreach-kaia/*"
]
}
]
}
```
⚠️ **Important**: Replace `your-company-outreach-kaia` with your actual bucket name
5. **In the policy tab**, click **"Next: Tags"** (optional)
6. **In the policy tab**, click **"Next: Review"**
7. **In the policy tab**, name your policy: `HindsightOutreachS3Access`
8. **In the policy tab**, click **"Create policy"**
9. **Close the policy tab** and **return to your user creation tab**
### 1.4 Attach the Policy to Your User
**Back in your user creation tab:**
1. Click the **refresh button** (🔄) next to the search box to load your new policy
2. In the search box, type: `HindsightOutreachS3Access`
3. **Check the checkbox** next to `HindsightOutreachS3Access` to select it
4. Click **"Next: Tags"** (optional)
5. Click **"Next: Review"**
6. Click **"Create user"**
### 1.5 Create Access Keys
After creating the user, you'll be taken to the user details page. Now you need to create access keys:
1. Click the **"Create access key"** button
2. Select **"Application running outside AWS"** as the use case
3. Click **"Next"**
4. Add a description tag (optional): `Hindsight S3 Integration`
5. Click **"Create access key"**
**What we're creating**: These are **programmatic access keys** (not console login credentials) that allow Hindsight to authenticate with AWS APIs to access your S3 bucket.
**Copy and save these values immediately**:
* **Access Key ID**: Starts with `AKIA...` (e.g., `AKIAIOSFODNN7EXAMPLE`)
* **Secret Access Key**: Long alphanumeric string (click **"Show"** to reveal, e.g., `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`)
⚠️ **Critical**: AWS will **never show the Secret Access Key again** after you close this page. If you lose it, you'll need to create new access keys.
⚠️ **Security Note**: These keys provide programmatic access to your S3 bucket. Store them securely (like in a password manager) and never share them publicly or commit them to code repositories.
***
## Step 2: Configure Outreach Export
### 2.1 Access Outreach Admin Panel
1. Log into Outreach with admin privileges
2. Navigate to **Administration** → **Tools** → **Kaia**
3. Find the **Bulk Export** section
### 2.2 Enable Daily Export
1. Toggle **"Bulk Export"** to ON
2. Select **"AWS S3"** as the service
3. Choose **"Daily Export"** as the export option
### 2.3 Configure S3 Settings
Enter your S3 bucket information:
* **S3 Region**: The region where you created your bucket (e.g., `us-east-1`)
* **S3 Bucket Name**: Your bucket name (e.g., `your-company-outreach-kaia`)
* **IAM Access Key ID**: From Step 1.5
* **IAM Access Secret**: From Step 1.5
### 2.4 Test and Save
1. Click **"Test Connection"** to verify the setup
2. If successful, click **"Save"** to enable daily exports
⚠️ **Note**: Outreach will retry failed exports for up to 48 hours. You'll receive email notifications about export status.
***
## Step 3: Connect to Hindsight
### 3.1 Navigate to Integrations
1. Go to [Hindsight Integrations](https://app.usehindsight.com/settings/integrations)
2. Find the **Outreach** integration card
3. Click **"Connect"** to start the OAuth process
### 3.2 Authorize Outreach
1. Complete the OAuth authorization with Outreach
2. This connects Hindsight to your Outreach account for user and deal matching
### 3.3 Configure S3 Access
After OAuth, you'll see the S3 configuration form:
Enter your S3 details:
* **S3 Region**: Same as configured in Outreach
* **S3 Bucket Name**: Your bucket name
* **Access Key ID**: From Step 1.5
* **Secret Access Key**: From Step 1.5
### 3.4 Test Connection
1. Click **"Test Connection"** to verify Hindsight can access your bucket
2. If successful, click **"Save Configuration"**
***
## Verification & Usage
### Daily Sync Process
Once configured, the integration works automatically:
1. **Outreach Export**: Every day, Outreach exports new Kaia recordings to your S3 bucket
2. **Hindsight Sync**: During your regular Salesforce/HubSpot deal syncs, Hindsight checks for new call transcripts
3. **Automatic Matching**: Hindsight matches calls to deals based on:
* Participant email addresses
* Account domains
* Call timing relative to deal dates
* Outreach user assignments
### Monitoring Integration Health
Check integration status on the [Integrations page](https://app.usehindsight.com/settings/integrations):
* **Connection Status**: Shows if Outreach and S3 are connected
* **Last Sync**: When Hindsight last processed new files
* **Files Processed**: Number of transcripts processed today
* **Transcripts Matched**: How many were successfully matched to deals
### Viewing Call Transcripts in Deals
Once calls are matched to deals, you'll see them in:
1. **Deal Documents**: Call transcripts appear as documents in your deals
2. **Competitive Insights**: AI-extracted insights from calls
3. **Battlecards**: Competitive intelligence from your calls
***
## Troubleshooting
### Common Issues
#### "S3 Access Denied" Error
* **Cause**: Incorrect IAM permissions or access keys
* **Solution**:
1. Verify your S3 bucket name matches exactly
2. Check IAM policy has correct bucket ARN
3. Ensure access keys are entered correctly
4. Test S3 access from AWS Console
#### "No Files Found"
* **Cause**: Outreach export not working or no calls in timeframe
* **Solution**:
1. Check Outreach export status in admin panel
2. Verify calls exist in the expected timeframe
3. Wait 24-48 hours for initial export to complete
#### "Low Match Rate"
* **Cause**: Calls not matching to deals properly
* **Solution**:
1. Ensure deal contact emails match call participants
2. Check deal date ranges include call timestamps
3. Verify Outreach users are mapped correctly
### Getting Help
If you encounter issues:
1. Check the [sync logs](https://app.usehindsight.com/settings/integrations) for error details
2. Reach out via your Slack Connect channel
3. Email [support@usehindsight.com](mailto:support@usehindsight.com) with:
* Your organization name
* Screenshot of any error messages
* S3 bucket name (do not include access keys)
***
## Security & Privacy
Review the permissions and data-handling settings for both Hindsight and the connected S3 bucket before enabling this integration. For current security information, contact Hindsight support.
# Salesforce Integration
Source: https://docs.usehindsight.com/integrations/salesforce-integration
Sync Hindsight with Salesforce CRM for Deal Analysis
## Overview
Hindsight connects to Salesforce via OAuth to sync your deals and analyze them for competitive win-loss insights. This guide will help you set up the integration and start using it effectively.
![Dashboard]()
For support, please reach out via your Slack Connect channel or via [email](mailto:support@usehindsight.com)
### How it Works
When you connect Hindsight to your Salesforce CRM, you'll be able to **import specific Opportunities into Hindsight**. Hindsight will analyze these Opportunities to extract competitive insights based on your decision drivers.
You can set up **automation rules** in Hindsight that automatically import Opportunities based on custom criteria. You can use your Salesforce data to **filter in the Win-Loss dashboard** and analyze your Opportunities based on specific criteria, such as stage, amount, or close date.
![integrations]()
### Daily Sync
**Opportunties are synced for the latest data every 12 hours**. This means that any changes made to your Opportunities in Salesforce will be reflected in Hindsight automatically.
Hindsight listens to opportunities via webhooks to make this seamless for users.
Deal Import Automation only applies to deals that meet your criteria AND which have closed within 12 hours of the sync.
If you make changes to your Deal Import Automation rules, these changes will be applied on the next Daily Sync.
If you'd like to pull in deals immediately or from outside the 12 hour window, you can manually import them via the [Deals](https://app.usehindsight.com/deals) page.
### Supported Objects
Hindsight only syncs objects associated with the Opportunities that you import. This includes:
* Opportunity
* Account
* Contacts
* Custom Fields
* Feed Items
* Emails
* Meetings
![slack deal]()
### Segments
**You can configure [segments](https://app.usehindsight.com/settings/segments) in Hindsight to filter your Opportunities based on custom criteria.** This allows you to analyze specific subsets of your Opportunities, such as those with a certain stage, amount, or close date.
Segments are useful for analyzing your Opportunities based on specific criteria, such as:
* Opportunities with a certain stage or pipeline (e.g. "Closed Won, New Business")
* Opportunities with a certain amount (e.g. "> \$10,000")
* Opportunities with a certain close date (e.g. "Next 30 days")
* Opportunities with a certain account type (e.g. "Enterprise")
* Opportunities with a certain product (e.g. "Product A")
* Opportunities with a certain region (e.g. "North America")
![slack deal]()
## Connecting Salesforce
### Authorization
**Authorizing Salesforce requires admin access to your Salesforce account.** Click "Connect" on the [integrations](https://app.usehindsight.com/settings/integrations) page and follow the authorization steps.
This will redirect you to the Salesforce authorization page. Click "Allow" to authorize Hindsight to access your Salesforce account. If you're having issues, contact your Salesforce admin.
![slack deal]()
### Import Rules
Setting up import rules allows you to **automatically import Opportunities into Hindsight** based on custom criteria. This is useful for keeping Hindsight's insights up-to-date without manual intervention.
We recommend filtering to Closed Won and Lost opportunities. You can also filter by custom fields, such as "Region" or "Product", to analyze specific subsets of your Opportunities.
![slack deal]()
## Security
Hindsight treats your Salesforce credentials and data as sensitive by default. The integration is built to meet the OAuth hardening controls that modern security programs (including Salesforce's own partner requirements) expect.
### OAuth Token Controls
| Control | Status | What it does |
| -------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PKCE** (Proof Key for Code Exchange) | Enforced | The authorization flow uses PKCE (S256), preventing authorization-code interception. |
| **Refresh Token Rotation** | Enforced | Each token refresh issues a new refresh token and invalidates the previous one, so a stolen token stops working after its first use. |
| **Idle Token TTL (30 days)** | Enforced | Refresh tokens expire after 30 days of inactivity, eliminating indefinitely-lived credentials. |
| **IP-Bound Token Refresh** | Available | Token-refresh requests originate exclusively from Hindsight's dedicated, self-hosted integration layer, enabling refresh requests to be bound to an approved IP range. |
### How Credentials Are Handled
* **Never exposed to the browser.** OAuth is brokered entirely server-side. Access and refresh tokens are held only by Hindsight's integration layer and are never returned to the client.
* **Encrypted at rest.** Tokens are stored encrypted in an internal-only database with no public network exposure.
* **Least-privilege scopes.** Hindsight requests only the specific Salesforce API scopes required for the features you use, not broad or full-account access.
* **Revocable at any time.** Disconnecting Salesforce from the [Integrations](https://app.usehindsight.com/settings/integrations) page immediately revokes Hindsight's access.
## Customization
### Opportunity Stages
To help Hindsight understand your custom opportunity stages, navigate to the [CRM Settings](https://app.usehindsight.com/settings/properties) and click the "Stages" tab.
**Mark your custom opportunity stages as "Closed Won" or "Closed Lost"** to help Hindsight analyze your Opportunities correctly. This will allow Hindsight to tag your Opportunities with the correct status and provide accurate win-loss insights.
![slack deal]()
### Custom Properties
You can customize the properties that Hindsight uses to analyze your opportunities in [CRM Settings](https://app.usehindsight.com/settings/properties) on the "Deals", "Accounts", and "Contacts". Having more properties makes analysis and sync slower, so "turn off"
You can map your custom properties to Hindsight's default properties like "Region", "Type", and "Amount". Properties that are "Synced" but not mapped to a Hindsight property will still be analyzed and available for filtering.
![slack deal]()
## Push to CRM
After Hindsight analyzes a deal, it automatically writes structured win-loss data back to the corresponding Salesforce Opportunity. This lets your team access insights directly in Salesforce without leaving their workflow.
### How It Works
Once analysis is complete, Hindsight patches the Opportunity record in Salesforce with a set of custom fields. These fields are created on your Salesforce Opportunity object under the `WL_` namespace. **You must run the field setup from the [Integrations](https://app.usehindsight.com/settings/integrations) page before data will appear** — Hindsight will not write to fields that don't exist yet.
### Default Fields
Hindsight populates the following fields on each analyzed Opportunity:
#### Core Metadata
| Salesforce Field | Label | Type | Description |
| --------------------- | ---------------------- | ---- | ----------------------------------------- |
| `WL_Date_Analyzed__c` | Win/Loss Analysis Date | Date | Date the win-loss analysis was completed. |
#### Primary Win/Loss Reason
| Salesforce Field | Label | Type | Description |
| ------------------------------- | ----------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `WL_Reason_Primary__c` | Primary Win/Loss Reason | Text (255) | Short label of the main reason for win/loss (e.g. "Pricing", "Ease of Use"). |
| `WL_Reason_Primary_Category__c` | Primary Reason Category | Picklist | Higher-level category. One of: `product`, `sales_execution`, `relationship`, `pricing`, `competitor`, `implementation`, `buyer_behavior`. |
| `WL_Reason_Primary_Impact__c` | Primary Reason Impact | Number (0–1) | Normalized impact score, where 1.0 = highest impact. |
| `WL_Reason_Primary_Summary__c` | Primary Reason Summary | Long Text | 1–2 sentence plain-language summary of the primary reason. |
#### Secondary Win/Loss Reason
| Salesforce Field | Label | Type | Description |
| --------------------------------- | ------------------------- | ------------ | ------------------------------------------------- |
| `WL_Reason_Secondary__c` | Secondary Reason | Text (255) | Label for the second-most impactful reason. |
| `WL_Reason_Secondary_Category__c` | Secondary Reason Category | Picklist | Same category options as primary reason. |
| `WL_Reason_Secondary_Impact__c` | Secondary Reason Impact | Number (0–1) | Normalized impact score for the secondary reason. |
| `WL_Reason_Secondary_Summary__c` | Secondary Reason Summary | Long Text | Summary of the secondary reason's impact. |
#### Competitor Intelligence
| Salesforce Field | Label | Type | Description |
| ------------------------------- | ----------------------- | ---------- | --------------------------------------------------------------------------------- |
| `WL_Competitor__c` | Primary Competitor | Text (255) | Name of the primary competitor identified in the deal (if any). |
| `WL_Competitor_Is_Incumbent__c` | Competitor Is Incumbent | Picklist | Whether the competitor was the incumbent. Values: `true` (Yes) or `false` (No). |
| `WL_Competitor_Outcome__c` | Competitor Outcome | Picklist | How the competitor featured in the deal: `mentioned`, `evaluated`, or `selected`. |
| `WL_Competitor_Reason__c` | Competitor Reason | Long Text | Positioning summary and key differentiators for the competitor. |
#### Quantitative Scores
All scores are on a **1–5 scale**.
| Salesforce Field | Label | Type | Description |
| ----------------------------- | --------------------- | ------ | ---------------------------------------------------------- |
| `WL_Product_Fit_Score__c` | Product Fit Score | Number | How well the product matched the buyer's requirements. |
| `WL_Sales_Execution_Score__c` | Sales Execution Score | Number | Quality of the sales team's execution throughout the deal. |
| `WL_Relationship_Score__c` | Relationship Score | Number | Strength of the buyer relationship. |
| `WL_Price_Sensitivity__c` | Price Sensitivity | Number | How price-sensitive the buyer was. |
| `WL_Competitive_Intensity__c` | Competitive Intensity | Number | How competitive the deal environment was. |
#### Narrative
| Salesforce Field | Label | Type | Description |
| ------------------ | ---------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| `WL_Deal_Story__c` | Deal Story | Long Text (2000) | Executive summary narrative of what happened in the deal — useful for coaching and enablement. |
### Custom Field Mappings
In addition to the default fields above, you can map **custom questions** and **custom metrics** configured in your Hindsight workspace to any Salesforce Opportunity field. To set this up, navigate to [Settings → Questions](https://app.usehindsight.com/settings/questions) and assign a Salesforce field API name to each question or metric.
When Hindsight writes to Salesforce, any custom answer or metric with a field mapping will be included in the same update as the default fields.
# Slack Integration
Source: https://docs.usehindsight.com/integrations/slack
Add Hindsight to Your Slack Workspace
### Overview
Hindsight's integration for Slack allows you to deliver battlecards, alerts, answers, and other insights directly to your sales team.
For teams using Hindsight for win-loss interviews, Hindsight's AI will conduct debriefs in Slack.
This guide will help you set up the integration and start using it effectively.
![Slack App]()
Disclaimer: AI generated responses may not be 100% accurate. Messages from Slack will not be used to train LLMs. User data is retained for only the time necessary to generate a response.
## Set Up
### Add Hindsight to Your Slack Workspace
Go to the [integrations](https://app.usehindsight.com/settings/integrations) page and click "Connect". This will redirect you to the Slack authorization page. Click "Allow" to add Hindsight to your Slack workspace.
![Integrations]()
### Get Admin Permissions (if neccessary)
If you are not an admin of your Slack workspace, you may need to request admin permissions to add Hindsight to your workspace. This is required to allow Hindsight to send notifications and deliver battlecards to your sales team.
Once approved, you'll have to add Hindsight to your workspace again. Click "Connect" on the [integrations](https://app.usehindsight.com/settings/integrations) page and follow the authorization steps again.
![Slack Admin Approval]()
### Add to Slack Channels
Once Hindsight is added to your Slack workspace, you can add it to specific channels. This will allow Hindsight to send notifications and deliver battlecards to those channels.
### Configure Real-Time Alerts
You can customize the types of Alerts you want to receive in Slack in the [Alerts](https://app.usehindsight.com/settings/alerts) page. Here, you can choose which types of alerts you want to receive.
![Slack Settings]()
The alerts currently available are:
1. **Competitor Update**: Get notified when Hindsight detects a significant piece of new intel. You can choose the sensititivty of these alerts.
2. **Newsleeter**: You can receive a weekly newsletter summarizing the latest competitive intelligence and insights from Hindsight.
3. **Competitive Deals**: You can receive insights on competitive deals that are being won or lost. This will help you understand how your competitors are performing in the market
### Configure Personal Notifications
You can customize the types of personal notifications you want to receive in Slack in the [Notifications](https://app.usehindsight.com/settings/notifications) page. Here, you can choose which types of notifications you want to receive as a DM from the Hindsight Slack App.
![Slack Notifications]()
The notifications currently available are:
1. **Weekly Digest**: Admin notification that lets you know about deals that need to be analyzed, pending interviews, and other important updates.
2. **Weekly Competitive Updates**: Get a weekly summary of the latest competitive intelligence and insights from Hindsight.
3. **Win-Loss Report**: A wekely report summarizing the latest win-loss insights from your team.
## Win-Loss interviews
If you are using Hindsight for win-loss interviews, you can conduct debriefs directly in Slack. Hindsight's AI will ask questions and gather insights from your team members in a Slack channel. This will help you analyze your wins and losses more effectively.
![Slack Win-Loss]()
### Using Voice Inputs for Win-Loss Interviews
Your sales team can record audio clips to answer questions during win-loss interviews in Slack. This feature allows for more natural and detailed responses, making it easier to capture insights from your team.
To use this feature, simply click the microphone icon in the message input box and record your response. Hit enter to submit the audio. Slack will transcribe this audio clip and send it as a message to Hindsight's AI interviewer, which will continue the interview.
## Sales Enablemement
### Instant Battlecards
You can get battlecards in Slack by typing `/battlecard [competitor name]` in any channel where Hindsight is added. This will deliver a simplified view of the battlecard directly to that channel.
![Slack Battlecards]()
### Instant Answers
You can ask Hindsight questions about your competitors by tagging Hindsight in a message - `@Hindsight [your question]`. Hindsight will respond with the most relevant information from your battlecards and insights.
![Slack Answers]()
### Competitive Newsletter
You can receive a weekly newsletter summarizing the latest competitive intelligence and insights from Hindsight. This will help you stay up-to-date with the latest developments in your competitive landscape.
![Slack Newsletter]()
## Crowdsource Competitive Intel
You can add intelligence from Slack into Hindsight by using the 3 dot menu on any message. Click "More actions" and select "Add to Hindsight". This will allow you to add competitive insights from your Slack conversations directly into Hindsight for analysis.
# Zapier Integration
Source: https://docs.usehindsight.com/integrations/zapier
Send Hindsight workflow outputs to 1000s of apps
## Overview
Hindsight's Zapier integration allows you to send the outputs of your workflows to thousands of apps without needing us to build a native integration. For example, you can automatically create a slide deck in [Gamma.ai](https://gamma.ai) from a Hindsight workflow output.
The Zapier integration is currently invite-only. [Request access in the app](https://app.usehindsight.com/settings/integrations) to get started. You'll receive an invite to use the Zapier integration in your email.
## Create a Zap
When creating a Zap, select **Hindsight** as the Trigger app. You should see Hindsight (1.3.0) as the version.
## Authenticate your Hindsight account
Generate an API key from the [API Keys](https://app.usehindsight.com/settings/keys) page. Paste your API key when connecting your Hindsight account to the Accounts tab in Zapier to authenticate.
![API Keys]()
## Set up your Trigger
Choose a workflow as your trigger—this will fire whenever that workflow completes. You'll see a test output to help you map the data to your action app.
![Zap Action]()
## Configure your Action
Select your destination app (e.g., Gamma.ai, Google Slides, Notion) and map the workflow output fields to your action. You'll typically want to use the Report Content field.
This allows you to automatically send Hindsight workflow results to your connected apps.
![Zap Action]()
## Test and Enable
Test your Zap to make sure everything is working correctly, then turn it on to start automatically sending workflow outputs to your connected apps.
***
## Using Hindsight as an Action
You can also use Hindsight as an Action to send data *into* Hindsight from other apps. This is useful for importing documents from meeting notetakers and other sources.
### Create a Zap with Hindsight Action
Select your trigger app (e.g., a meeting notetaker like Fathom), then select **Hindsight** as the Action app. Choose the **Create Document** action to create a new document in your Hindsight account whenever the Zap is triggered.
![Zap Action]()
### Map your fields
Map the fields from your trigger app to the fields in Hindsight. This will allow you to send data from your trigger app to Hindsight when the Zap is triggered.
![Zap Action Settings]()
### Test and turn on your Zap
Test your Zap to make sure everything is working correctly. This will send a test document to your Hindsight account. Once verified, turn on your Zap to start sending data.
![Deal Documents]()
# Deal Memory for AI Agents
Source: https://docs.usehindsight.com/overview
Turn fragmented GTM evidence into a verified, continuously updated memory of every account and deal—queryable over MCP and the REST API.
Hindsight is the **deal memory layer** for your GTM stack. It continuously turns the evidence scattered across calls, emails, CRM records, documents, and warehouse data into a verified, structured memory of each account and opportunity.
The result is more than a deal summary. Hindsight reconstructs what happened, why it happened, and how the team executed; preserves the supporting evidence; and makes relevant prior experience available when a new opportunity needs it. Your team and AI agents can query that memory directly through the [Model Context Protocol (MCP)](/integrations/mcp) or the [REST API](/integrations/api).
For **RevOps and enablement**, this creates a dependable operating record without relying on manual CRM hygiene. For **AI engineers**, it provides a cited, workspace-scoped tool surface—without building ingestion, retrieval, entity resolution, comparison, and verification infrastructure for every workflow.
![Hindsight platform: GTM data sources flow into the Analyze Engine, which builds verified account and deal memory, reachable over MCP and the REST API by people, agents, and custom workflows.]()
***
## Why deal memory
Every opportunity generates experience, but most organizations cannot reuse it. The evidence is distributed, inconsistently labeled, and difficult for a person—or an agent—to evaluate in the context of the next deal.
Deal context is split across call recordings, email threads, CRM fields, documents, and systems of record—without a canonical view of the opportunity.
CRM fields are incomplete, terms vary by team, and transcripts are noisy. Raw retrieval alone cannot establish what actually happened or which evidence supports a conclusion.
Prior wins and losses stay trapped in source systems. Teams repeatedly research the same objections, buyer requirements, and execution risks instead of applying proven experience.
***
## How Hindsight builds deal memory
At the core is the **Analyze Engine**. For each deal, it aggregates related calls, emails, CRM records, documents, and other available evidence. It reconciles that evidence into an account and deal record that captures the commercial context, outcome, and supporting sources.
The memory captures dimensions that make past experience comparable and reusable: buyer and stakeholder context, product signals, competitive position, decision drivers, commercial fit, and sales execution. As new evidence arrives and deals advance, Hindsight refreshes the record rather than leaving a point-in-time summary behind.
Every tool reads from this memory layer. Retrieval, reconciliation, and evidence linking happen server-side, so agents can work from clean, cited context instead of reprocessing raw transcripts on every call.
Each conclusion remains linked to source evidence and confidence signals, so users can inspect what was actually said and resolve uncertainty.
The memory evolves as opportunities progress, close, and receive new context—so the next workflow can use the most current available experience.
### Data sources
**Your CRM is the backbone — and the only required source.** Connect Salesforce or HubSpot and Hindsight pulls each opportunity and its associated objects, along with the related account and contact objects. You control exactly which properties come across from the **CRM settings page** in your dashboard. For many teams that's enough on its own—the CRM is already the centralizer, and Hindsight builds the verified deal memory from what is there.
**Context sources are optional enrichment.** When you want more than what lives on the CRM record — full call transcripts and the actual content behind a deal — connect dedicated sources and Hindsight ingests the full signal:
| Type | Sources |
| -------------- | -------------------------------------------------------------------------------------- |
| CRM (required) | Salesforce, HubSpot |
| Calls | Gong, Clari, Outreach Kaia, Fathom, Fireflies, Avoma |
| API | Upload any document or transcript directly — see [REST API uploads](/integrations/api) |
Hindsight is **format-flexible**: PDFs, Office files, Markdown, audio, and video are all ingested, and call recordings are transcribed automatically.
**Warehouse your data in Snowflake?** On the Enterprise plan, Hindsight can ingest directly via a Snowflake data share — no manual exports or uploads required.
### Sync & analysis cadence
By default, Hindsight pulls the latest from connected integrations **every 12 hours** while a deal is open and continues for **14 days after it closes**. By default, deal analysis re-runs on **every stage change** and whenever **new context sources are uploaded**—so the deal memory stays current as the opportunity moves.
You control when deal analysis runs. **Enterprise customers can also configure custom integration sync schedules** to match their data-refresh and operating requirements.
***
## Query and apply the memory
Hindsight is API-first. Query account and deal memory through two integration surfaces, then use the resulting experience in your agents, applications, and operating workflows.
A composable tool surface your AI assistant orchestrates directly. Use it to inspect deal context, find comparable experience, retrieve evidence, and analyze pipeline data in Claude, ChatGPT, Cursor, Cline, or your own MCP client. **Start here for agent use cases.**
A single endpoint that runs Hindsight's agent server-side and returns a complete, cited answer. Best for Glean, Slack bots, embedded search, and workflows that want a finished response.
**Rule of thumb:** use **MCP** when *your* model should choose the tools and control the execution path. Use the **REST API** when you want Hindsight to orchestrate retrieval and synthesis, then return a cited answer.
Authentication is the same for both — a Bearer API key scoped to your workspace. Generate one from **Settings → API Keys** in the [Hindsight app](https://app.usehindsight.com/settings/keys).
***
## Tools available
The MCP server exposes the deal memory layer as a focused set of tools. They fall into seven groups. Most agent workflows start with **`fetch_hindsight_context`** to learn the workspace's competitors and deal stages, then branch into the relevant group.
### Context & schema
Orient the agent before it queries — what competitors and stages exist, and what fields the deal grid has.
| Tool | Description |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| `fetch_hindsight_context` | Fetch competitors and deal stages needed to use the other tools. Usually the first call. |
| `pull_schema` | Fetch the CRM field schema for your workspace — field names and types for the deal grid. |
### Deals & pipeline
Find, triage, and read individual deals and their underlying documents.
| Tool | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| `select_deal` | Filter and list deals by criteria. Returns lean rows for fast triage. |
| `get_deal` | Get full details for specific deals by ID. |
| `search_comparable_deals` | Find the most comparable historical deals for a source deal, including each matching dimension and score. |
| `search_across_deals` | Search all deal documents across the entire pipeline. |
| `search_deal_documents` | Deep search within specific deals. |
| `pull_full_document` | Fetch full document content by ID when retrieved chunks aren't enough. |
### Competitive intelligence
Query your competitive content and saved intel.
| Tool | Description |
| --------------------------- | ------------------------------------------ |
| `search_competitive_assets` | Search battlecards and competitive assets. |
| `search_competitive_intel` | Search pre-saved competitive intelligence. |
### Knowledge base
| Tool | Description |
| ----------------------- | ----------------------------------------------------------------- |
| `search_knowledge_base` | Search your company's messaging docs, playbooks, and positioning. |
### Live web research
Reach beyond stored data for current market and competitor information.
| Tool | Description |
| --------------- | ---------------------------------------------------- |
| `search_web` | Live web search for competitive and market research. |
| `scrape_url` | Extract content from a specific URL. |
| `map_site_urls` | Discover and map the structure of a website. |
### Quantitative analysis
Build and analyze structured datasets from the deal grid for win-rate, trend, and segment questions.
| Tool | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_dataset` | Build a structured dataset from your deal pipeline. |
| `run_sandbox_dataset_analysis` | Run custom Python analysis against an authorized dataset in Hindsight's isolated, network-disabled sandbox. Can return up to three charts. |
### Write back
| Tool | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `upload_deal_document` | Attach a document to a deal — pass the text directly or a downloadable file URL. |
| `upload_to_knowledge_base` | Upload your company's docs, playbooks, case studies, or approved messaging to the knowledge base. |
| `upload_competitive_intel` | Save competitor pricing, positioning, feature notes, or gathered news to the knowledge base. |
Tool availability is role-based. By default, workspace admins can use every tool; managers can use the read tools plus the data-analysis tools; and members can use the read tools. Workspace admins can customize these permissions in **Settings → MCP Tools**.
The canonical tool list is generated from the live MCP server. Names and parameters can change between releases — call `tools/list` against the [MCP endpoint](/integrations/mcp) for the exact current surface.
***
## What this enables
An operational memory for win-loss, competitive attribution, and rep execution. Identify which patterns matter, find comparable deals, and improve the next motion without hand-maintaining a secondary system of record.
A clean, cited tool surface for agents and applications. Give workflows access to grounded deal experience over MCP or REST instead of implementing a bespoke retrieval and verification pipeline.
### Trust & governance
User-scoped OAuth and role-based access control help ensure every answer is scoped to your workspace and traceable to its source documents.
***
## Next steps
Wire Hindsight into Claude, ChatGPT, Cursor, or your own MCP client.
Get complete, cited answers from a single endpoint.
Generate a workspace-scoped key from the dashboard.
# Competitive Enablement
Source: https://docs.usehindsight.com/quickstart-ci
Stand up your competitive enablement agent in four steps
Get your competitive enablement agent live in four steps. By the end, your reps can tag **@Hindsight** in Slack and get answers grounded in your content and tracked competitor pages — without you maintaining a single battlecard by hand.
Everything below happens in the [setup flow](https://app.usehindsight.com/competitors/setup). It saves as you go, so you can stop and come back anytime.
Hindsight pre-fills the grid with **suggested competitors from your market**, so you usually start with a list already in front of you.
Review the suggestions, then:
* **Edit or remove** any that don't fit
* **Add competitors** manually — enter a name or website and Hindsight enriches the logo and description automatically
* **Import a CSV** (name, website, category) to add many at once
* Optionally set a **category** so reps still get guidance for competitors without a named card
Keep whatever's in the grid — those become your tracked competitors when you continue.
For each competitor, give the agent something to ground its answers in:
* **Upload your content** — battlecards, objection handling, one-pagers, decks. Connect **Google Drive, Notion, or Confluence**, or upload files directly. The agent draws from your library first, so the more you add, the better day-one answers are.
* **Choose web pages to track** — pick the pages Hindsight watches for changes (pricing, changelog, blog, G2). It scrapes them into your intel library and keeps them current automatically.
* **Add URL filters** (optional) — restrict the agent's web research to authoritative sources like their docs or pricing page, keeping answers grounded.
Files about your own company — playbook, messaging, ICP — go under **"You"**.
Continue to the agent step, where you can test a real question against a **live Slack simulation** — ask exactly what a rep would mid-deal:
> *@Hindsight how do we beat \[Competitor X] in an enterprise deal?*
Then shape how the agent responds:
* **Custom instructions** — tone, positioning rules, things to always (or never) say, so the agent stays on message
* **Notifications** — route feedback and answer activity to the right Slack channel or people
If an answer looks thin, that's signal — go back and add more content for that competitor.
Put the agent where your reps already work:
* **Connect Slack** from the setup screen, then invite Hindsight to a channel like **#compete**
* Reps tag **@Hindsight** in any channel — or DM it directly — to get an answer grounded in your library and tracked pages
* **MCP endpoint** (optional) — use the same agent inside Claude, ChatGPT, or any other AI tool. See the [MCP docs](https://docs.usehindsight.com/integrations/mcp).
That's it — your competitive enablement agent is live.
## What's Next
Build battlecards and enablement content from verified deal data that stays current automatically.
Set up automated monitoring with skills and workflows to track competitor changes on a cadence.
Learn how to organize and maintain your competitive intelligence library for accurate AI answers.
# MCP 2.0
Source: https://docs.usehindsight.com/release-notes/mcp-2.0
OAuth sign-in, direct tool calls, and the first stable release of the Hindsight MCP server
Hindsight MCP 2.0 is the **first stable release** of our Model Context Protocol server. It moves authentication to OAuth, replaces the old single-agent entry point with direct tool calls, and ships a round of reliability fixes.
**This is a breaking change.** Connections built against the pre-2.0 server need to be reconnected. The upside: 2.0 is now our stable contract — tool names, auth, and behavior won't shift underneath you the way the preview server could. See [What you need to do](#what-you-need-to-do) below.
***
## OAuth is now the primary sign-in
The MCP server now authenticates with **OAuth** as the primary flow. When you install the [Hindsight connector](https://app.usehindsight.com/hindsight.mcpb), Claude opens your browser, you sign in to Hindsight, and you pick the workspace to use — no copying API keys into a config file.
**What changed under the hood:** access is granted through Clerk-issued OAuth tokens, verified per request, with automatic token refresh. The server advertises an OAuth-protected-resource endpoint so compatible clients can discover and complete the sign-in flow on their own.
**What it means for you:**
* **Per-user access, not a shared key.** Each person signs in as themselves, and access is scoped to the workspace they select — better security and cleaner usage attribution.
* **Simpler setup.** The one-click connector handles auth end-to-end; there's nothing to paste or rotate.
* **API keys still work** for manual/headless setups. Bearer-key configs (`Authorization: Bearer YOUR_API_KEY`) remain supported as a fallback — useful for servers and CI. See the [MCP setup guide](/integrations/mcp).
***
## Direct tool calls
The biggest architectural change: the server now exposes Hindsight's capabilities as **individual tools your assistant calls directly**, instead of routing everything through a single orchestrating agent that spun up sub-agents behind the scenes.
Your assistant now calls focused tools like `fetch_hindsight_context`, `select_deal`, `get_deal`, `search_deal_documents`, `create_dataset`, and `analyze_dealgrid_subset` itself — and chains them as it sees fit.
**What it means for you:**
* **Faster responses.** Skipping the extra agent-orchestration layer cuts latency — simple questions don't pay for a full sub-agent spin-up.
* **Fine-grained control.** You can see exactly which tool runs at each step, approve or deny individual calls, and disable tools you don't want exposed. Nothing happens inside an opaque agent loop.
* **Better composability.** Your own model decides how to combine Hindsight's tools with everything else it can reach, which is what makes the server a clean building block for custom agents and skills.
The canonical tool list is generated from the live server. For the current surface and how the tools fit together, see the [Platform Overview](/overview#tools-available) and [MCP docs](/integrations/mcp).
***
## Fixes & reliability
* **Cross-origin support** — added CORS handling (including preflight `OPTIONS`) so browser-based clients like Claude and ChatGPT on the web connect cleanly.
* **OAuth resource resolution** — the protected-resource URL is now derived from the deployment's site URL, fixing discovery in production.
* **Tool-result parsing** — more robust extraction of result summaries so responses render reliably across clients.
* **Tool-call rendering** — corrected how in-progress tool calls display during a response.
***
## What you need to do
If you connected to the preview server, reconnect against 2.0:
1. **Reinstall the connector** — download the latest [hindsight.mcpb](https://app.usehindsight.com/hindsight.mcpb) and install it in Claude. You'll be prompted to sign in with OAuth and select your workspace.
2. **Or update your manual config** to point at `https://app.usehindsight.com/api/mcp`. API-key Bearer auth still works for manual setups.
3. **Re-check tool permissions** in your client — with direct tool calls, you control which tools are enabled.
Full instructions live in the [MCP setup guide](/integrations/mcp).
***
## Coming soon
**Web MCP as an official Claude connector.** We're working with Anthropic to offer Hindsight as a one-click connector inside Claude on the web — no local bundle to install. The OAuth flow in this release is the groundwork for it.
# Release Notes
Source: https://docs.usehindsight.com/release-notes/release-notes
Summary of major updates
## August 2026
Comparable Deals for learning from similar past opportunities, Sales Plays in beta, and new Paige capabilities for deal-grounded chat, sandboxed data analysis, and specialized workflows.
### Comparable Deals
Find past opportunities most similar to the deal you are working, based on evidence from calls, notes, and CRM data—not just fields such as industry or deal size.
**Evidence-backed matches** — Each match includes an auditable rationale and usefulness rating, so you can see why it was surfaced.
**AI research briefs** — Paige researches each candidate deal before scoring it, adding context beyond what's in the raw data.
**Faster, better-prioritized results** — Background matching prioritizes recent deals, so results arrive quickly and remain relevant.
### Sales Plays
Plays has moved from Alpha to Beta and expanded beyond win-back and upsell opportunities. Build proactive Sales Plays with custom trigger conditions, prompt-based instructions, and attached playbooks.
When a trigger is met—for example, a deal reaches stage 2 with two or more competitors—the Hindsight Agent follows your instructions and alerts reps in Slack or email. Reps can continue the work in Slack, Claude, ChatGPT, or Hindsight.
### Chat & Analysis
Paige can now run custom Python scripts in a secure sandbox for more flexible data analysis. Ask it to analyze a dataset and return charts you can expand, copy, or download. Scripts can also be twice as long, supporting more complex requests.
Type `/` in chat to add specific deals, datasets, or skills as context for your question. Pasted text now appears outside the message input, making the context easier to review before you send.
Skills now fully replace Recipes. Every team starts with four default skills for **competitive enablement**, **Hindsight deal research**, **data analysis**, and **deal strategy**. Add custom skills from the [Skills page](https://app.usehindsight.com/skills).
The Hindsight Agent loads the right skills dynamically, so you do not need to select them manually.
Reasoning and in-progress work now appear in collapsible chat sections, making responses easier to follow without adding clutter.
Long responses now checkpoint progress and finish within a time budget instead of stalling. Paige can also look up comparable deals directly in chat.
Fixed shared-thread replies inadvertently taking over a session and avatars failing to render on some messages.
### Admin Controls
Admins can disable individual report and skill types so teams see only relevant Slack outputs.
### Platform
All existing workflows have migrated automatically—no action is needed. Workflows are now prompt-based, can reference skills without depending on them, and work like scheduled chat conversations. This makes them much easier to edit and manage.
Import Decision Drivers from a CSV on the Drivers page instead of adding them one at a time.
## July 2026
MCP 2.0, stronger controls for Custom Metrics and Answers, faster dashboard filtering, more reliable Snowflake syncs, and new Slack and interview improvements.
### Developer Tools
OAuth is now the primary sign-in method, and capabilities are exposed as **direct tool calls** for faster responses and per-tool control rather than through a single orchestrating agent. This breaking change establishes our first stable contract and includes CORS and reliability fixes.
Hindsight is now a Claude Community Connector.
[Read the full MCP 2.0 notes →](/release-notes/mcp-2.0)
Admins can choose available MCP tools and add per-tool instructions, keeping Claude, ChatGPT, and other clients aligned with your team's conventions. Connections also stay signed in longer, and tools now have clearer names and error messages.
MCP clients can now write documents to Hindsight, not just read them. Each tool accepts in-context text or a downloadable file URL and uses the same processing pipeline as the app.
**`upload_deal_document`** — attach a transcript, note, or file to a specific deal.
**`upload_to_knowledge_base`** — add your own docs, playbooks, case studies, or approved messaging.
**`upload_competitive_intel`** — save competitor pricing, positioning, or gathered news.
See the [MCP tool reference](/integrations/mcp#available-tools).
Trial organizations now receive Growth-tier API rate limits automatically, so you can fully evaluate the API before subscribing.
### CRM Integration
Snowflake imports now include a dedicated preview, like our other CRM integrations, so you can see exactly which deals will be imported. Filters and sorting stay in sync, refreshed deals match more accurately, and improved duplicate detection covers synced notes, meetings, and emails.
**On-demand resync** — Snowflake-connected orgs can now trigger a manual resync of their deals right from the deal grid instead of waiting for the next scheduled sync.
A pipeline health check flags HubSpot deals missing from Hindsight and lets you bulk-import them in one click.
### Chat & Analysis
Chat responses now include a collapsible “Thinking…” section, so you can follow the AI's work alongside the final answer. Citation rendering is cleaner throughout.
### Custom Metrics & Answers
Set conditions for when Custom Metrics and Answers are evaluated. Add filters to any metric or answer—for example, Stage 2+ or deal size over \$50K—for more precise control.
Metrics and Custom Answers now use multi-step analysis of deal context rather than a single retrieval pass, improving accuracy for complex questions.
Group related Custom Metrics for easier configuration and review. You can also disable Hindsight's default metrics and use only your own.
Attach playbooks, guides, and approved messaging to Custom Answers so the AI uses them as context across your deals, just as it does for Custom Metrics.
### Dashboard & Analytics
Browse Product Intelligence by feature, product, or product area. Improved column selectors across the deals and features grids make Product Taxonomy easier to manage.
One-click filters on the Dashboard and Settings pages take you to common views faster. Your last-used filters are remembered between visits; new sessions default to the current quarter, and **Reset filters** restores the defaults.
### Slack
Slack Assistant replies now include buttons to continue in Claude or ChatGPT with your question pre-filled, so you can dig deeper without retyping context.
### Win-Loss Interviews
Interview-request recipients can opt out with a one-click unsubscribe link and will not be contacted again.
## June 2026
Sales Plays in alpha, unified usage analytics, role-based MCP access, GDPR support for EU surveys, and the Hindsight MCP server in Claude and ChatGPT.
### Sales Plays (Alpha)
Turn competitive intelligence into action on live deals.
**AI-generated plays** — Hindsight recommends plays using deal context and competitive signals.
**Outreach drafting in Slack** — Draft tailored outreach directly from a Slack thread, with messaging adapted to the play type.
**Linked assets** — Attach enablement assets so reps have the right collateral at hand.
**Email notifications** — Get notified by email when a new play opportunity is ready to act on.
### Sales Enablement
**Filtering and stats** — Filter questions by user, topic, rating, or channel (Slack, web, MCP, or API) to understand adoption and impact.
**Readable names** — Slack channels and users now resolve to their real names throughout the assistant view.
Redesigned competitor onboarding, with new enablement and setup pages for a smoother first-run experience.
### Win-Loss Interviews
Voice interviews now use the GA Azure real-time API for more stable connections, with automatic connection retries and clearer voice-only instructions. Failures now surface clearly instead of silently falling back to text.
EU surveys now include GDPR-compliant consent capture and support for response deletion requests.
### Platform
MCP tool permissions now differentiate among admins, managers, and members. Configure them in the Hindsight settings dashboard.
The Hindsight MCP server is now available through the Claude and ChatGPT marketplaces, with new tools and OAuth sign-in via Clerk-issued tokens for secure, per-user access.
The new `/v1/deals` endpoint returns real-time, paginated deal data with filtering and rate limiting. The interview-types API now also supports custom guidelines and analysis fields.
## May 2026
A new AI Win-loss Interview experience, and more customizeable Product Intelligence.
### Platform
A major upgrade to how Hindsight tags and organizes product feedback, making it far easier to track what buyers care about across your deals.
**Customizable feature tag types** — Define your own feature tag types instead of relying on fixed categories, so tagging maps to how your team actually thinks about the product.
**Smarter tagging logic** — Reworked tagging logic produces more accurate, consistent tags across interviews and documents.
**Cleaner tagging UI** — Updated components make reviewing and managing product tags faster and more intuitive.
### Win-Loss Interviews
**Detailed viewer** — A new per-interview page shows response analytics and takeaways for each respondent.
**Response stats** — The feedback page now shows total responses, completion count, completion rate, and last response time per interview type.
**Re-analyze** — Reprocess a document or interview on demand to refresh its analysis, with support for dynamic analysis fields per interview type.
**Better defaults** — Improved default analysis fields with placeholders and structured select/boolean options for cleaner setup.
**ElevenLabs transcription** — Higher-quality transcription for voice interviews.
**Cleaner voice experience** — Microphone selection now persists across panel reopens, duplicate voice messages are eliminated, and an improved noise gate prevents the AI's own speech from cutting itself off.
**Recording fixes** — Corrected WebM recording durations and fixed video playback and scrubbing across the viewer.
The Google Meet bot now joins, records, and saves interview recordings, with improved session handling and webhook reliability.
Share public, open interview links for public interview types — no individual request required. Contact notes can now be viewed and edited inline, and partial responses are saved if a respondent closes the tab mid-interview.
Sequences now surface attention indicators for pending approvals, outstanding rewards, and missing data, plus an upload-contacts dialog on the feedback page.
### CRM Integration
Better handling of `previous_status` filters and "import all closed deals," plus corrected stage ordering in opportunity-history queries.
## April 2026
Interview Sequences, Snowflake CRM support, demo interview summaries, and the Hindsight MCP server with OAuth.
### Win-Loss Interviews
A new way to manage multi-step interview campaigns end to end.
**Default templates & cloning** — Start from built-in sequence variants, clone existing sequences, and auto-save as you edit.
**Enrollments** — A new Enrollments tab on each sequence shows who's enrolled, with search and filtering. Queued enrollments process automatically when a sequence is enabled.
**Email logging** — An Emails tab on each sequence surfaces every message sent as part of that sequence.
**Approvals** — Approve interview requests inline; approval links now route through sequence-based URLs.
Send demo interview summaries directly from Hindsight for quick sharing and review.
### CRM Integration
Initial support for importing deals from a Snowflake data warehouse, including a sync orchestrator and ID mapping to align Snowflake records with internal deal IDs.
### Platform
Connect Hindsight directly to Claude, Cursor, and any other MCP-compatible client — bringing your competitive intelligence, win-loss insights, and deal data into the tools your team already works in.
**One-click OAuth sign-in** — Authenticate the MCP server with OAuth and org-membership validation, so only authorized users in your workspace get access — no manual API key handling required.
**Production-ready bundle** — A branded, production-configured MCPB bundle (`.mcpb`) makes installation a single step.
**Built on the Hindsight API** — The server exposes Hindsight's chat, library, and deal tools so agents can search and reason over your data in context.
Fixed NPS ratings for customers on Slack Enterprise Grid — messages now route to the correct workspace via `team_id` for enterprise installs.
## March 2026
Video interviews, automatic gift card redemptions, richer manual sending controls, a smarter Slack agent, and a handful of platform improvements.
### Win-Loss Interviews
**Video & audio recording** — Buyers can now complete interviews via video or audio recording, alongside the existing text flow.
**Updated interview UI** — Cleaner, more polished experience for buyers throughout.
**Centralized responses** — All responses, including recordings, are saved to the [Responses](https://app.usehindsight.com/responses) library for easy review and filtering.
**Automatic fulfillment** — Set a gift card budget in your interview settings and Hindsight handles fulfillment automatically via Tremendous.
**No manual tracking** — Incentives go out as soon as a buyer completes their interview. Configure your [Budget](https://app.usehindsight.com/settings/usage) in the Settings menu.
The Interview Agent now handles end-to-end interview coordination automatically — no manual outreach required. When a deal closes, the agent reads deal context, sends personalized Slack interviews to your team, reaches out to buyers by email, manages approvals, and follows up with non-responders.
**Automated Internal Interviews** — Personalized Slack DMs go out to the deal owner and collaborators as soon as the agent runs, with a tailored opening question based on the deal outcome — no warm-up needed.
**Buyer Outreach** — Sends email interview requests to buyer-side contacts using your configured templates, with support for multiple variants (e.g. different incentive levels or buyer segments).
**Approval Workflows** — Optionally gate buyer outreach behind an approval step — approvers get notified via Slack and email and can approve with a single click.
**Automatic Follow-Ups** — The agent re-pings non-responders and reminds approvers who haven't acted, so nothing falls through the cracks.
**Custom Instructions** — Inject freeform routing logic directly into the agent's prompt — for example, route interviews to specific roles, use higher-incentive templates for enterprise accounts, or skip external outreach for SMB losses.
Configure the agent under **Settings → Interview Agent**. See the [Win-Loss Interviews guide](/guides/win-loss-interviews) for full setup details.
New options on the `/feedback/send` page give you more control over how interview requests go out.
**Queue requests manually** — Add requests to the interview agent's queue, including follow-up scheduling and approval handling.
**One-off requests** — Send requests with custom topics outside of your standard interview template.
**CSV export** — Export custom requests to import into Apollo, Outreach, or any other sequencing tool.
### Slack Agent
The Slack agent has moved to the main agent harness and now runs as a competitive intelligence subagent, with support for subagent-level rules.
**Richer search** — Can now search the web, your asset library, and stored intel to answer questions in context.
**Multi-step queries** — Better handling of queries that require multiple sources or reasoning steps.
**Faster responses** — Improved answer formatting and noticeably faster response times.
### Competitive Intelligence
Add URL-based restrictions to control which sources the research agent can pull from for a given competitor. This lets you limit the agent to only pull from specific domains or subdomains that you trust as authoritative for that competitor, so that the research results are scoped appropriately.
**Scope to trusted sources** — Limit a competitor's research to specific domains or subdomains, such as their own docs subdomain.
**Setup** — Hit the 3-dots menu next to any competitor in the [Competitors](https://app.usehindsight.com/competitors) list and select **Edit URL rules**.
### Platform
You can now integrate Hindsight's competitive intelligence, win-loss insights, and deal data directly into your AI agents, MCP servers, Glean, Slack bots, or custom applications.
![API Keys]()
**Chat / Responses Endpoint** — Send messages to Hindsight's AI and get fully synthesized, cited answers — Hindsight handles the tool orchestration for you.
**Streaming Support** — Get real-time streamed responses via SSE for lower-latency integrations.
**Document Upload — Library** — Programmatically upload competitive intelligence and enablement assets to your Hindsight Library, with support for competitor tagging and source tracking.
**Document Upload — Deals** — Associate documents and audio files (auto-transcribed) with specific deals by Hindsight, Salesforce, or HubSpot ID.
Get your API keys from **Settings → API Keys**. See the [API docs](/integrations/api) for endpoint references and request formats.
Insert Deal Datasets directly into the chat from the Chat page, giving you more flexibility to bring structured deal data into any conversation — including mid-session.
![Opening Deal Grid in Chat]()
Click the button at the bottom left of the chat input to open the dataset dialog. Apply filters to scope the dataset to the deals you care about, then insert it into the chat. The dataset will be added as context for your current conversation.
![Inserting Deal Grid Mid Session]()
Rolling out updated colors and typography across main pages. More areas of the app will follow over the coming weeks.
**Query preview** — View the exact SOQL query Hindsight generates from your import settings and filters before any deals are pulled in.
**Deal preview** — See the set of deals that will be imported so you can validate your configuration before going live.
**Improved filter logic** — Better support for AND / OR, IN, and NOT IN filters, as well as complex groupings.
**Set member titles** — Admins can now set and edit titles for team members directly within Hindsight.
**Use in agent rules** — Titles are available as a condition in agent rules — for example, routing interview decisions based on whether the owner is an AE.
## February 2026
Another month, another set of powerful updates to Hindsight. This year is all about AI Agents.
More power, more simplicity. For some teams, this may be a breaking change.
### Competitor Monitoring Agent
We've rebuilt competitive monitoring from the ground up, now powered by Hindsight's AI agent and workflows system.
NOTE: this means the older competitor monitoring system (e.g. News Feed) will stop functioning fully in 4 weeks. Please work with your account manager to help ensure a successful transition or use our Guides to set up the new system yourself.
Key capabilities include:
* **Expanded Data Sources**: Access LinkedIn content, G2 reviews, and other web content on your competitors via the AI chat, in your recipes, and from scheduled workflows
* **Full Customization**: Configure your own monitoring schedule, notification style, delivery channels, and more
* **Seamless Migration**: Existing competitor monitoring setups have been automatically migrated to the new system
* **Remixable Recipes**: Each workflow starts with a default Recipe that you can remix and customize to deliver updates exactly the way you want them
### New Research Tools
We've promoted several research tools to production and added new experimental capabilities for deeper web research.
Now generally available:
* **Web Search**: Search the web for real-time competitive intelligence, market trends, and industry news
* **Scrape Tool**: Extract content from any webpage to bring into your analysis
Experimental:
* **Map URL Tool**: Automatically discover and index subpages from a given URL
* **Browse Tool**: Full browser capabilities for research on specialized or bot-protected sources like LinkedIn
### Intel Library
Save the links and resources your Agent discovers to the new Intel Library—a dedicated space for competitive intelligence and research materials.
Find it under the Library tab in the left sidebar.
Key capabilities include:
* **Centralized Organization**: Keep approved, high-quality insights organized and easily accessible
* **Team Access**: Surface materials via the Slack Agent and other enablement workflows
* **Auto-Sync**: Saved pages are automatically indexed and synced on a regular cadence to stay up to date and detect changes
## January 2026
Happy New Year! We're kicking off 2026 with some exciting new features and enhancements to help your team win more deals.
Along with product updates, we're also offering 1:1 onboarding sessions to help you get the most out of Hindsight and all the new capabilities.
If you have a workflow you'd like help setting up, or if you'd like a walkthrough of the new features, please reach out!
### Workflows!
Workflows let you automate the delivery of insights, reports, and assets to your team on a recurring schedule. Build custom workflows that run recipes automatically and deliver results via Slack, email, or directly to your Library.
Key capabilities include:
* **Scheduled Runs**: Set recipes to run daily, weekly, or on a custom cadence
* **Multiple Delivery Channels**: Push insights directly to specific Slack channels, email lists, or Slack DMs
* **Library Integration**: Create or update existing assets and documents in your Library (e.g., battlecards, competitor profiles)
* **External Tool Connections**: Use Zapier to send outputs to your Google Drive, Gamma, or other AI systems
### Metrics Enhancements
We've made several enhancements to our metrics capabilities to provide you with deeper insights and more flexibility in how you evaluate deals.
#### Metrics Scoring Guidelines
You can now choose documents to use as guidelines for the model to reference when scoring a deal. For example, when scoring sales execution,
you might want to provide your sales playbook or coaching guide as a reference to ensure consistent scoring aligned with your organization's standards.
When configuring a Custom Metric, simply select one or more documents from your Library to use as scoring guidelines. The AI will reference these documents when evaluating and scoring each deal.
#### New Metrics
We've added three new default Custom Metrics to help you better evaluate deal dynamics:
* **Customer Fit**: Measures how well your product aligns with the customer's needs and requirements
* **Messaging Fit**: Assesses how effectively your messaging resonates with the customer's pain points and objectives
* **Messaging Accuracy**: Evaluates how accurately your messaging reflects your product's capabilities and differentiators
#### Filtering by Metric Scores
You can now filter deals based on their Custom Metric scores. This allows you to quickly identify deals that meet specific scoring criteria, such as low sales execution or low product fit.
When building datasets or running analyses, simply apply filters based on the desired metric scores to focus on the most relevant deals for your insights. These filtering capabilities allow you to build smarter alerting workflows so you can quickly flag opportunities that need attention.
### Web Search Tool (Experimental)
We've introduced an experimental Web Search tool that allows you to augment AI analyses with real-time information from the web. This is particularly useful for gathering the latest competitive intelligence, market trends, and industry news that may not be present in your existing deal data.
You can ask the Agent to find new material on the internet, and then click to save it the right competitor's CI library.
This improves the customization of your newsletters and other workflows.
### Agent Harness Enhancements
#### Model Upgrade
All Accounts are now upgraded to OpenAI's GPT 5.1.
#### Tool Usage
We've improved the Agent's ability to use tools effectively during analysis. This includes better selection of when to invoke specific tools, improved handling of tool outputs, and enhanced integration with external data sources.
#### Context Management
The Agent can now manage larger contexts more effectively, allowing it to analyze more complex datasets and extract deeper insights without losing track of important details.
#### Enhanced Data Analysis
Agent can now segment data more accurately allowing for more nuanced and insightful reports.
## December 2025
### Data Analyst Agent V2
We've significantly upgraded the Data Analyst Agent in Chat, enabling powerful analytics across your entire deal library.
Key improvements include:
* **Unlimited Dataset Size**: Analyze thousands of deals at once, removing previous limits on dataset size
* **AI-Powered Pattern Recognition**: Leverages outputs from AI Deal Reviews to surface patterns in competition, product fit, sales execution, and more
* **Dynamic Visualizations**: AI automatically builds charts and graphs to illustrate key findings
* **Recursive Segmentation**: Automatically segments data to drill down into trends and outliers
* **Quantitative + Qualitative Insights**: Combines statistical analysis with contextual understanding for comprehensive insights
* **New Dataset UI**: Improved interface for viewing, exploring, and exporting datasets and segments used in analysis
Coming soon:
* **Advanced Segmentation**: More sophisticated segmentation capabilities for deeper analysis
* **Enhanced Visualizations**: Additional chart types and customization options
### Slack Admin & Usage Analytics
New admin controls and usage analytics for the Hindsight Slack Assistant.
Key capabilities include:
* **Custom System Prompt**: Configure a custom system prompt to tailor AI responses in Slack to your team's tone, terminology, and guidelines
* **Competitive Intel Toggle**: Control whether the Slack Assistant can search and surface competitive intelligence data
* **Usage Analytics**: Track how many questions are being asked in Slack over time, identify top topics and competitors being queried, and see which team members are engaging most with the assistant
These settings give admins more control over the Slack experience while providing visibility into how teams are leveraging AI assistance.
### Variables in Recipes
Recipes now support configurable variables, making it easier to create flexible, reusable analysis workflows that can be quickly customized at runtime.
Key capabilities include:
* **Text Variables**: Add simple text inputs that users fill in when running a recipe (e.g., competitor name for a **Top Objections** recipe)
* **Filter Variables**: Let users apply Deal filters at runtime (e.g., filter a **Product Gaps** report to your Enterprise segment, or filter a **Win Themes** report to deals won in the last quarter)
This makes Recipes more accessible for teams who want standardized workflows with the flexibility to adapt each run to their specific needs.
You can configure variables when building or remixing a recipe in the Recipe Builder. You can make variables required or optional, and set default values for both text and filter variables.
## November 2025
### Recipes (Beta)
We've launched Recipes, a powerful new way to create, customize, and run reusable analysis workflows that deliver insights tailored to your team's specific needs.
Key capabilities include:
* **Role-Based Recipe Library**: Pre-built recipes organized by function (Product Management, Marketing, Competitive Intelligence, Sales Enablement, Operations) help teams get started quickly with relevant analyses
* **Two Modes**:
* **Deal Research Agent**: AI agent finds and deeply analyzes relevant data from up to 25 deals at a time, using call transcripts, notes and other deal context without dataset configuration
* **Data Analyst Agent**: Build custom datasets with advanced filtering and column selection, then analyze up to 100 deals at once with your chosen prompt
* **Remix & Customize**: Start with any Hindsight default recipe and remix it to create your own version with custom filters, columns, and prompts that match your specific workflows
* **Recipe Management**: Save, organize, and share recipes across your team for consistent analysis approaches
Coming soon:
* **Scheduled Recipes**: Automatically run recipes on a schedule to keep insights fresh
* **Share Results**: Distribute recipe outputs directly to Slack channels or via email
Recipes make it easy to standardize how your team analyzes deals while maintaining the flexibility to adapt to evolving business needs. Whether you're tracking competitive win rates, analyzing product feedback patterns, or coaching sales execution, Recipes help you get consistent, actionable insights faster.
## October 2025
### Auto-suggested Drivers, Competitors, Features
We now automatically suggest new labels when AI analyzes deals, dramatically expanding your ability to track and analyze deal dynamics without manual configuration.
Key capabilities include:
* **Unlimited Labeling**: Track unlimited competitors, drivers, or features without pre-configuration
* **Smart Detection**: When new topics are detected in deals, we automatically create suggested tags (shown with lightbulb icons to accept/decline)
* **Expanded Competitive Intelligence**: Competitors can include insights on your team vs. DIY, homegrown, or other alternatives
* **Roadmap Integration**: Features can include both current capabilities and roadmap items, plus competitor capabilities
* **Enhanced Accuracy**: More labels provide more detailed insights and improved AI accuracy, as the system has less incentive to match weakly correlated quotes to existing labels
This feature eliminates the need for extensive upfront configuration while ensuring comprehensive deal analysis coverage.
### Trend Analysis
We added comprehensive trend analysis to help you understand how competitive dynamics, decision drivers, and feature importance evolve over time.
Features include:
* **Multi-timeframe Views**: Switch between 7-day, 30-day, 90-day, Year-to-Date, and All-time statistics
* **Visual Change Indicators**: Clear visual indicators showing changes and trends over time
* **Decision Driver Trends**: See how often specific decision drivers are cited in deals over time
* **Competitive Deal Volume and Win Rate Trends**: See how deal volume and win rates for competitors and drivers change over selected timeframes
* **Feature Mention Trends**: Track how often specific features are mentioned in deals over time
This enables teams to identify emerging patterns, seasonal trends, and long-term shifts in market dynamics.
### Decision Driver Table
We launched a dedicated Decision Drivers page (`/drivers`) for comprehensive driver management and analytics.
The new interface provides:
* **Centralized Driver Stats**: View performance metrics and usage statistics for all decision drivers
* **Driver Configuration**: Streamlined setup and management of custom decision drivers
* **Enhanced Organization**: Better categorization and bulk management tools for large driver libraries
This complements our existing Decision Drivers functionality with improved visibility and management capabilities.
### Reports (Beta)
We've graduated our Reports functionality from Alpha to Beta with significant improvements to the analysis engine and user experience. Reports now provide more sophisticated AI-powered insights and enhanced dataset customization options.
Key improvements include:
* **Enhanced AI Analysis**: Improved pattern recognition and insight generation with structured reporting templates
* **Advanced Dataset Builder**: More granular filtering options including custom properties, deal segments, and timeframe controls
* **Expanded Report Types**: Pre-built templates for win/loss analysis, competitive intelligence, product feedback, and sales execution
* **Report Management**: Complete reports library with saving, sharing, and collaboration features
* **CSV Export**: Download configured datasets for custom analysis in external tools
* **Conversational Follow-up**: Continue refining analysis through chat interface after report generation
The beta release supports analysis of up to 100 deals at once and includes comprehensive prompt customization for tailored business insights. See full documentation: [/platform/activate/custom-reports](/platform/activate/custom-reports)
## September 2025
### Competitive Intelligence Revamp
We refreshed our competitive tracking workflow to improve usability, controls, and human-in-the-loop processes. Key updates include:
* Ability to configure completely custom URL tracking for competitors. Track any webpage on a custom scraping schedule to meet your needs
* Improved event detection with AI, including deduplication of similar events and better extraction of event details
* New event triage workflow to review, edit, and approve detected events before they are shared with your team
* Slack notifications to alert competitor owners when new events are detected and ready for triage
### Chat with this Data (Beta)
We added an integrated chat experience built around the various data tables in Hindsight. This allows users to create custom .csv files with win/loss and competitive data,
then pass that data to Hindsight's AI assistant to answer questions, extract insights, and build reports.
### Reports (Alpha)
We released an early version of Hindsight's native Reports functionality. Reports allow users to use powerful, pre-built prompt templates to generate reports based on their deal data.
* 4 default reports released, spanning Win/Loss, Competitive Intel, Product, Marketing, and Sales topics
* Ability to customize report data by filtering to any custom criteria (e.g. region, product, time period)
* Completely customizable reports via prompting and further data exploration with help of AI assistant
* Reports library for creating, managing, and sharing reports across your Team
### RBAC (Role-Based Access Control)
We launched Role-Based Access Control (RBAC) to help admins manage user permissions and data access. Members are assigned limited permissions to perform specific actions, while Admins have full access to all features and settings.
## August 2025
### Push to CRM (Beta)
We added Push to CRM functionality for Custom Answers and Custom Metrics, enabling automatic syncing of qualitative insights and scoring frameworks directly to your CRM. This ensures that critical deal information is consistently updated in your CRM, enhancing visibility and alignment across sales teams.
### Clari Copilot Integration
We launched a native integration with Clari Copilot, allowing seamless integration of Clari Copilot call transcripts with the Hindsight platform
### Outreach Kaia Integration
We launched an integration with Outreach Kaia call transcripts, enabling users to leverage Outreach Kaia's call transcripts and insights within the Hindsight platform.
### Chat with this Deal
We added an integrated chat window on individual deal reports, allowing users to interact with AI in the context of a specific deal without having to leave the page. This allows for simple queries and workflows built off of deal review data.
## July 2025
### Assets
We introduced Chat-to-Asset creation so you can convert any AI chat response into a permanent, shareable document in your Library. Titles and optional competitor tags improve organization and discovery, while a markdown editor lets you refine content before sharing.
Assets integrate with Slack so teams can surface relevant materials in-channel, and a centralized Library makes search and access simple. Common use cases include battlecards, objection guides, product comparisons, one-pagers, and other sales collateral. See full notes: [/release-notes/assets](/release-notes/assets)
### Custom Answers
Custom Answers lets you define prompts once and automatically run them across all deals to fill qualitative data gaps. Answers can be true/false, one sentence, or paragraph length, and are derived from full deal context (CRM, transcripts, summaries, interviews). You can review, export, and optionally push answers to CRM.
This standardizes “free-form” insights like main objection, champion identified, decision maker, or coaching takeaways—enabling consistent analysis at scale. See full notes: [/release-notes/custom-answers](/release-notes/custom-answers)
### Custom Metrics
Create 1–5 scoring frameworks tailored to your business with rubrics, categories, and rules for when to score. Five enhanced default metrics (Sales Execution, Relationship, Pricing Fit, Product Fit, Competitive Performance) help you start fast, and scores come with explanations and manual overrides.
Metrics are visualized in Analytics with bar/line charts, multi-select comparisons, and segment filters, so you can spot trends, correlate with outcomes, and guide coaching. See full notes: [/release-notes/custom-metrics](/release-notes/custom-metrics)
### Decision Drivers Upgrade
We launched a pre-built library of decision drivers organized into six categories (Sales Execution, Relationship, Pricing & Packaging, Product & Features, Implementation & Support, Buyer Behavior). This makes setup dramatically faster, while retaining full customization and backward compatibility with existing drivers.
The new interface improves discovery, bulk selection, and organization, helping teams standardize definitions and improve analysis coverage. See full notes: [/release-notes/decision-drivers-2.0](/release-notes/decision-drivers-2.0)
### Feature Tracking 2.0
A rebuilt feature tracking system adds a dedicated Features dashboard, AI-powered detection of feature mentions in deals, better analytics (mentions, sentiment, revenue impact), and improved competitive analysis with evidence-backed comparisons. Data is consolidated for performance and accuracy, with a cleaner UX and automatic migration for existing data.
The result is clearer visibility into which capabilities drive revenue, cleaner comparisons against competitors, and more actionable feedback loops for product and sales. See full notes: [/release-notes/feature-tracking-2.0](/release-notes/feature-tracking-2.0)
# Security & Compliance
Source: https://docs.usehindsight.com/security-compliance
Security controls supported by Hindsight API and MCP access
Hindsight API keys support explicit least-privilege scopes, expiration or revocation, live organization-membership validation, per-key and organization-wide rate limiting, and per-operation audit logging for supported API and MCP actions.