Get Deals - Hindsight Docs

GET

deals

curl "https://app.usehindsight.com/api/v1/deals?page_size=20&sort=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "deal_123",
    "name": "Acme Corp - Enterprise License",
    "amount": 50000,
    "status_id": "negotiation",
    "previous_status_id": "qualification",
    "proposal_due": "2026-03-15",
    "created_at": "2023-11-07T05:31:56Z",
    "owner_id": "<string>",
    "salesforce_id": "<string>",
    "hubspot_id": "<string>",
    "deal_analyzed": true,
    "analysis_verified": true,
    "type": "New Business",
    "region": "<string>",
    "deal_competitor_associations": [
      {
        "competitor_id": "<string>",
        "is_primary": true,
        "is_incumbent": true
      }
    ],
    "drivers": [
      {
        "reason_id": "<string>",
        "positive": true,
        "summary": "<string>"
      }
    ],
    "wl_product_fit_score": 123,
    "wl_sales_execution_score": 123,
    "wl_relationship_score": 123
  }
]

Retrieve deals with flexible filtering, sorting, and pagination. Returns deal objects with all their properties and relationships.

Copy for AI context

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 as bulk export)
  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})
  competitor: string (JSON array of competitor IDs)
  competitor_filter_type: "is any of" | "is not"
  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"
  deal_analyzed: string (JSON array: ["true"] or ["false"])
  analysis_verified: string (JSON array: ["true"] or ["false"])
  # ... 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",
    "proposal_due": "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": true,
    "type": "New Business",
    "region": "North America",
    "deal_competitor_associations": [
      {
        "competitor_id": "comp_123",
        "is_primary": true,
        "is_incumbent": false
      }
    ],
    "drivers": [
      {
        "reason_id": "reason_456",
        "positive": true,
        "summary": "Strong product fit"
      }
    ],
    "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: 60 req/min (Essentials), 300 req/min (Growth), 1000 req/min (Enterprise)

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

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 names to return. Use `*` for all columns. See Available Columns for the full list.

Limit returned data to only the fields you need to reduce response size and improve performance. Example:

GET /deals?columns=name,amount,deal_status,proposal_due,owner_id
GET /deals?columns=*  # All columns (default)

For a complete list of available columns (standard and dynamic), see the Available Columns section in the Bulk Export Deals documentation.

Search

Parameter	Type	Description
`searchQuery`	string	Fuzzy search across deal names

Example:

GET /deals?searchQuery=acme

Filters

All filters from the bulk export endpoint are supported. Filters are passed as query parameters with JSON-encoded values for arrays and objects.

Deal Identification

Filter	Type	Description	Example
`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
`competitor`	string	JSON array of competitor IDs	`["comp_123"]`
`competitor_filter_type`	string	Filter type	`is any of`
`any_competitor`	string	JSON array: `["true"]` or `["false"]`	`["true"]`

Analysis

Filter	Type	Description	Example
`deal_analyzed`	string	JSON array: `["true"]` or `["false"]`	`["true"]`
`analysis_verified`	string	JSON array: `["true"]` or `["false"]`	`["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
`hubspot_filters`	string	JSON array of HubSpot filter objects	See 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
proposal_due - 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=proposal_due&sort_order=asc
GET /deals?sort=amount&sort_order=desc

Response Format

Standard Response

Returns an array of deal objects with all requested fields:

[
  {
    "id": "deal_123",
    "name": "Acme Corp - Enterprise License",
    "amount": 50000,
    "status_id": "negotiation",
    "previous_status_id": "qualification",
    "proposal_due": "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": true,
    "type": "New Business",
    "region": "North America",
    "deal_competitor_associations": [
      {
        "competitor_id": "comp_123",
        "is_primary": true,
        "is_incumbent": false,
        "positioning_summary": "Main competitor evaluation"
      }
    ],
    "drivers": [
      {
        "reason_id": "reason_456",
        "positive": false,
        "summary": "Price too high compared to competitor"
      }
    ],
    "wl_product_fit_score": 4.2,
    "wl_sales_execution_score": 3.8,
    "wl_relationship_score": 4.5
  }
]

Count Response

When count=true, returns only the total count:

CRM Filters

For advanced filtering using CRM-specific properties:

GET /deals?salesforce_filters=[{"property":"Account.Industry","operator":"is","value":"Technology"}]

Salesforce filter object structure:

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

Plan	Requests per Minute
Essentials	60
Growth	300
Enterprise	1,000

Examples

curl "https://app.usehindsight.com/api/v1/deals?page_size=20&sort=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Use Pagination: Always paginate through large datasets rather than requesting all at once
Select Columns: Use the columns parameter to only fetch fields you need
Cache Counts: If you need counts frequently, cache them with appropriate TTL
Filter Server-Side: Apply filters in the API request rather than fetching all data and filtering client-side
Handle Rate Limits: Implement exponential backoff when you receive 429 responses
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	60-1000 req/min	5-100 exports/hour
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:

{
  "message": "Invalid filter format: close_date must be a valid JSON object"
}

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

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"

proposal_due

string<date>

Expected or actual close date

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

Show child attributes

drivers

object[]

Array of deal drivers/reasons

Show child attributes

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)

Bulk Export DealsGenerate 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.

curl "https://app.usehindsight.com/api/v1/deals?page_size=20&sort=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "deal_123",
    "name": "Acme Corp - Enterprise License",
    "amount": 50000,
    "status_id": "negotiation",
    "previous_status_id": "qualification",
    "proposal_due": "2026-03-15",
    "created_at": "2023-11-07T05:31:56Z",
    "owner_id": "<string>",
    "salesforce_id": "<string>",
    "hubspot_id": "<string>",
    "deal_analyzed": true,
    "analysis_verified": true,
    "type": "New Business",
    "region": "<string>",
    "deal_competitor_associations": [
      {
        "competitor_id": "<string>",
        "is_primary": true,
        "is_incumbent": true
      }
    ],
    "drivers": [
      {
        "reason_id": "<string>",
        "positive": true,
        "summary": "<string>"
      }
    ],
    "wl_product_fit_score": 123,
    "wl_sales_execution_score": 123,
    "wl_relationship_score": 123
  }
]

​Overview

​Pagination

​Column Selection

​Search

​Filters

​Deal Identification

​Deal Attributes

​Date & Amount

​Competitive Intelligence

​Analysis

​Win-Loss Scores

​CRM Filters (Advanced)

​Segments

​Sorting

​Response Format

​Standard Response

​Count Response

​CRM Filters

​Rate Limits

​Examples

​Best Practices

​Comparison: Get Deals vs Bulk Export

​Error Responses

Authorizations

Query Parameters

Response

Overview

Pagination

Column Selection

Search

Filters

Deal Identification

Deal Attributes

Date & Amount

Competitive Intelligence

Analysis

Win-Loss Scores

CRM Filters (Advanced)

Segments

Sorting

Response Format

Standard Response

Count Response

CRM Filters

Rate Limits

Examples

Best Practices

Comparison: Get Deals vs Bulk Export

Error Responses