Get Deal

POST

tools

get-deal

curl -X POST https://app.usehindsight.com/api/v1/tools/get-deal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deal_ids": ["deal_123"] }'

{
  "total_returned": 123,
  "limit_applied": 123,
  "results": [
    {
      "type": "deal",
      "id": "<string>",
      "deal_id": "<string>",
      "name": "<string>",
      "client_name": "<string>",
      "stage": "<string>",
      "amount": 123,
      "close_date": "<string>",
      "url": "<string>",
      "summary": "<string>",
      "competitors": [
        {
          "name": "<string>",
          "positioning_summary": "<string>",
          "key_differentiators": "<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"
  }
}

Get full details for one or more known deals. Use Select Deal first when you need to find the relevant IDs.

POST https://app.usehindsight.com/api/v1/tools/get-deal

Request Body

Field	Type	Required	Description
`deal_ids`	string[]	Yes	One to ten deal IDs returned by `select-deal` or another Hindsight search. Duplicate IDs are ignored.

{
  "deal_ids": ["deal_123", "deal_456"]
}

Response

The response includes the same identifying fields as select-deal, plus the deal summary and per-competitor positioning.

{
  "total_returned": 1,
  "limit_applied": null,
  "results": [
    {
      "type": "deal",
      "id": "deal_123",
      "deal_id": "deal_123",
      "name": "Acme Enterprise Renewal",
      "client_name": "Acme Corp",
      "stage": "Closed Lost",
      "summary": "Acme selected the incumbent after raising pricing and implementation concerns.",
      "competitors": [
        {
          "name": "Example Competitor",
          "positioning_summary": "Positioned as the lower-risk incumbent.",
          "key_differentiators": "Existing integration and implementation support"
        }
      ],
      "url": "https://app.usehindsight.com/deals/deal_123/home"
    }
  ]
}

If a requested ID is not accessible to the authenticated organization or does not exist, it is omitted from results.

curl -X POST https://app.usehindsight.com/api/v1/tools/get-deal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deal_ids": ["deal_123"] }'

Limits and Errors

Organization-wide and per-API-key limits apply. See Rate limits for returned headers and retry guidance. A request with no IDs or more than ten IDs returns 400.

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

deal_ids

string[]

required

Required array length: 1 - 10 elements

Response

Detailed deal records

total_returned

integer

limit_applied

integer | null

results

object[]

Show child attributes

curl -X POST https://app.usehindsight.com/api/v1/tools/get-deal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deal_ids": ["deal_123"] }'

{
  "total_returned": 123,
  "limit_applied": 123,
  "results": [
    {
      "type": "deal",
      "id": "<string>",
      "deal_id": "<string>",
      "name": "<string>",
      "client_name": "<string>",
      "stage": "<string>",
      "amount": 123,
      "close_date": "<string>",
      "url": "<string>",
      "summary": "<string>",
      "competitors": [
        {
          "name": "<string>",
          "positioning_summary": "<string>",
          "key_differentiators": "<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