Bulk Export Deals - Hindsight Docs

POST

deals

export

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", "proposal_due", "owner_id"]
  }'

{
  "success": true,
  "export_id": "exp_abc123",
  "status": "pending",
  "message": "Export job started successfully",
  "estimated_completion": "2-3 minutes"
}

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.

Copy for AI context

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", "proposal_due", ...],  // 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: Per-minute (10/60/300 req/min for Essentials/Growth/Enterprise) + monthly quota per route.

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 for options.

Optional Filters

All filters are optional. If no filters are provided, all deals in your organization will be exported.

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
`salesforce_filters_account`	object[]	Account-level Salesforce properties (Account object)	See CRM Filters
`hubspot_filters`	object[]	Deal-level HubSpot properties	See CRM Filters
`hubspot_filters_account`	object[]	Account-level HubSpot properties (Company object)	See 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:

{
  "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.

Available Columns

Standard Columns

Column ID	Description
`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
`proposal_due`	Expected/actual close date
`created_at`	Deal creation date
`deal_analyzed`	Whether deal has been analyzed
`analysis_verified`	Whether analysis has been verified
`type`	Deal type (New Business, Expansion, Renewal)
`region`	Geographic region
`summary`	Executive summary of the deal

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”

Response

Initial Response (POST)

When you submit an export request, you’ll receive an export_id and status:

{
  "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:

{
  "export_id": "exp_abc123",
  "status": "pending",
  "created_at": "2026-03-10T12:00:00Z"
}

Response when complete:

{
  "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:

{
  "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:

{
  "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 is an object, not a string:

{ "property": { "id": "field_name" } }

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.

{
  "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

All API routes share a per-minute rate limit and a monthly usage quota. Per-minute limit (shared across all API routes):

Plan	Requests per Minute
Essentials	10
Growth	60
Enterprise	300

Monthly quota (per route, resets on the first of each month):

Plan	Exports per Month
Essentials	10,000
Growth	30,000
Enterprise	100,000

When a limit is exceeded, the API returns a 429 response with X-RateLimit-* and X-Usage-* headers indicating current usage and reset timing.

Examples

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", "proposal_due", "owner_id"]
  }'

Best Practices

Column Selection: Only request columns you need to minimize export size and processing time
Polling Interval: Wait 5-10 seconds between status checks to avoid rate limiting
Download Promptly: Download the file within 7 days before the URL expires
Filter Early: Apply filters to reduce export size rather than filtering after download
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:

{
  "error": "Invalid column IDs: unknown_column, invalid_field",
  "status": 400
}

Authorizations

Authorization

string

header

required

API key from Hindsight dashboard

Body

application/json

columns

string[]

required

Array of column IDs to include in the export

Example:

["name", "amount", "stage", "close_date"]

filters

object

Optional filters to apply

Show child attributes

Response

Export job started

success

boolean

Example:

true

export_id

string

Unique export job ID

Example:

"exp_abc123"

status

enum<string>

Initial status is always pending

Available options:

pending

message

string

Example:

"Export job started successfully"

estimated_completion

string

Example:

"2-3 minutes"

Upload to Knowledge BaseUpload competitive intelligence documents, assets, and other files to your library. Documents are automatically processed, chunked, and indexed for search.

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", "proposal_due", "owner_id"]
  }'

{
  "success": true,
  "export_id": "exp_abc123",
  "status": "pending",
  "message": "Export job started successfully",
  "estimated_completion": "2-3 minutes"
}

​Overview

​Request Format

​Required Fields

​Optional Filters

​Deal Identification

​People & Ownership

​Deal Attributes

​Date & Amount Filters

​Competitive Intelligence

​Analysis Filters

​CRM Filters (Advanced)

​Filter Type Modifiers

​Available Columns

​Standard Columns

​Dynamic Columns

​CRM Deal Properties

​CRM Account Properties

​Custom Metrics

​Custom Answers

​Response

​Initial Response (POST)

​Checking Export Status (GET)

​Download URL Expiration

​CRM Filters

​Rate Limits

​Examples

​Best Practices

​Error Responses

Authorizations

Body

Response

Overview

Request Format

Required Fields

Optional Filters

Deal Identification

People & Ownership

Deal Attributes

Date & Amount Filters

Competitive Intelligence

Analysis Filters

CRM Filters (Advanced)

Filter Type Modifiers

Available Columns

Standard Columns

Dynamic Columns

CRM Deal Properties

CRM Account Properties

Custom Metrics

Custom Answers

Response

Initial Response (POST)

Checking Export Status (GET)

Download URL Expiration

CRM Filters

Rate Limits

Examples

Best Practices

Error Responses