Select Deal

POST

tools

select-deal

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
  }'

{
  "total_returned": 123,
  "limit_applied": 123,
  "page": 123,
  "page_size": 123,
  "has_more": true,
  "next_page": 123,
  "results": [
    {
      "type": "deal",
      "id": "<string>",
      "deal_id": "<string>",
      "name": "<string>",
      "client_name": "<string>",
      "stage": "<string>",
      "amount": 123,
      "close_date": "<string>",
      "url": "<string>"
    }
  ]
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid parameters",
    "details": {
      "missing_fields": [
        "file_name"
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Your role (member) does not have permission to perform this action."
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the reset time in the response headers."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Find analyzed deals using structured filters. This endpoint returns lean rows for triage; use 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.

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

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 for returned headers and retry guidance. Invalid input returns 400; unauthorized or disallowed calls return 401 or 403.

Authorizations

Authorization

string

header

required

API key from Hindsight Settings → API keys. Use Authorization: Bearer YOUR_API_KEY. Newly created keys begin with hs_; existing keys remain supported until rotated or expired.

Body

application/json

query

string | null

Fuzzy deal or client-name match. Cannot be used with semantic_query or segment_id.

semantic_query

string | null

Conceptual search over deal content. Cannot be used with query or segment_id.

segment_id

string | null

Segment ID. Cannot be used with query.

competitor_id

string | null

deal_stage

One or more deal-stage names.

amount

object | null

Show child attributes

close_date

object | null

Show child attributes

type

string | null

region

string | null

owner_name

string | null

Owner name, email, or me, my, or mine.

limit

integer

default:20

Required range: 1 <= x <= 50

page

integer

default:1

Required range: x >= 1

Response

Matching deal rows

total_returned

integer

limit_applied

integer | null

page

integer

page_size

integer

has_more

boolean

next_page

integer | null

results

object[]

Show child attributes

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
  }'

{
  "total_returned": 123,
  "limit_applied": 123,
  "page": 123,
  "page_size": 123,
  "has_more": true,
  "next_page": 123,
  "results": [
    {
      "type": "deal",
      "id": "<string>",
      "deal_id": "<string>",
      "name": "<string>",
      "client_name": "<string>",
      "stage": "<string>",
      "amount": 123,
      "close_date": "<string>",
      "url": "<string>"
    }
  ]
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid parameters",
    "details": {
      "missing_fields": [
        "file_name"
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Your role (member) does not have permission to perform this action."
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the reset time in the response headers."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Overview

Get Started

MCP

Security & Compliance

REST API

Integrations

Release Notes

Request Body

Response

Limits and Errors

Authorizations

Body

Response

​Request Body

​Response

​Limits and Errors

Authorizations

Body

Response

Request Body

Response

Limits and Errors