Skip to main content
GET
Retrieve deals with flexible filtering, sorting, and pagination. Returns deal objects with all their properties and relationships.

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 endpoint instead.

Pagination

Example:

Column Selection

Limit returned data to only the fields you need to reduce response size and improve performance. Example:
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 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 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: 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.
Dynamic columns
The JSON response uses the requested selector as the property name:
Example:

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

Deal Attributes

Date & Amount

Competitive Intelligence

Analysis

Legacy filter aliases

Existing integrations do not need to change immediately. Both GET and bulk export continue to accept these earlier internal names: Legacy boolean filters may still use JSON arrays such as deal_analyzed=["true"].

Win-Loss Scores

Filters for deal analysis scores (range queries):

CRM Filters (Advanced)

Segments

Sorting

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:

Response Format

Standard Response

Returns an array of deal objects with all requested fields:

Drivers, competitors, and features

These three are relational fields, returned as flattened arrays (included with *, or by requesting the drivers, competitors, and features columns):

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:

CRM Filters

For advanced filtering using CRM-specific properties:
Salesforce filter object structure:
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

Examples

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

Error Responses

Example error response:

Authorizations

Authorization
string
header
required

API key from Hindsight dashboard

Query Parameters

page_size
integer
default:50

Number of deals per page

Required range: x <= 100
page_index
integer
default:0

Zero-based page index

count
boolean

If true, returns only the total count

sort
enum<string>

Column to sort by

Available options:
created_at,
updated_at,
close_date,
amount,
name
sort_order
enum<string>
default:desc

Sort direction

Available options:
asc,
desc
columns
string

Comma-separated list of columns to return

searchQuery
string

Fuzzy search across deal names

status
string

JSON array of deal stages

owner_ids
string

JSON array of owner IDs

close_date
string

JSON object: {"from": "2026-01-01", "to": "2026-03-31"}

amount
string

JSON object: {"min": 10000, "max": 100000}

Response

Successful response

id
string

Hindsight deal ID

Example:

"deal_123"

name
string

Deal name

Example:

"Acme Corp - Enterprise License"

amount
number

Deal value

Example:

50000

status_id
string

Current deal stage ID

Example:

"negotiation"

previous_status_id
string | null

Previous deal stage ID

Example:

"qualification"

close_date
string<date>

Expected or actual close date (internal field name: proposal_due)

Example:

"2026-03-15"

created_at
string<date-time>

Deal creation timestamp

owner_id
string

Deal owner ID

salesforce_id
string | null

Salesforce Opportunity ID

hubspot_id
string | null

HubSpot Deal ID

deal_analyzed
boolean

Whether deal has been analyzed

analysis_verified
boolean

Whether analysis has been verified

type
string | null

Type of deal

Example:

"New Business"

region
string | null

Geographic region

deal_competitor_associations
object[]

Array of competitor associations

drivers
object[]

Array of deal drivers/reasons

wl_product_fit_score
number | null

Product fit score (1-5)

wl_sales_execution_score
number | null

Sales execution score (1-5)

wl_relationship_score
number | null

Relationship score (1-5)