Upload to Deal

POST

deals

documents

curl -X POST https://app.usehindsight.com/api/v1/deals/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "Discovery Call Recording.mp3",
    "file_url": "https://example.com/recording.mp3",
    "content_type": "audio/mpeg",
    "salesforce_id": "006xxxxxxxxxxxx",
    "source": "gong"
  }'

const response = await fetch('https://app.usehindsight.com/api/v1/deals/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    file_name: 'Discovery Call Recording.mp3',
    file_url: 'https://example.com/recording.mp3',
    content_type: 'audio/mpeg',
    salesforce_id: '006xxxxxxxxxxxx',
    source: 'gong'
  })
});

const data = await response.json();
console.log(`Document uploaded: ${data.document.id}`);
console.log(`Processing run: ${data.run_id}`);

import requests

response = requests.post(
    'https://app.usehindsight.com/api/v1/deals/documents',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'file_name': 'Discovery Call Recording.mp3',
        'file_url': 'https://example.com/recording.mp3',
        'content_type': 'audio/mpeg',
        'salesforce_id': '006xxxxxxxxxxxx',
        'source': 'gong'
    }
)

data = response.json()
print(f"Document uploaded: {data['document']['id']}")
print(f"Processing run: {data['run_id']}")

{
  "document": {
    "id": "doc_abc123",
    "file_name": "Competitor X Pricing Guide.pdf",
    "status": "processing",
    "type": "asset",
    "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "run_id": "run_xyz789"
}

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

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

{
  "error": {
    "code": "not_found",
    "message": "Deal with the specified ID was not found"
  }
}

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

Associate documents with specific deals for win-loss analysis. Audio and video files are automatically transcribed.

Copy for AI context

POST https://app.usehindsight.com/api/v1/deals/documents
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Request fields (multipart/form-data):
  file_name: string (required)
  file_url: string (uri) — URL to fetch file from
  file: binary — binary file content (alternative to file_url)
  content_type: string (required) — MIME type, e.g. application/pdf, audio/mpeg, video/mp4
  deal_id: string — Hindsight deal ID
  salesforce_id: string — Salesforce Opportunity ID
  hubspot_id: string — HubSpot Deal ID
  source: gong | clari | fathom | fireflies | avoma | outreach | gmail | Salesforce | Hubspot | api
Provide exactly one of: deal_id, salesforce_id, or hubspot_id.

200 Response:
{
  "document": {
    "id": "doc_abc123",
    "file_name": "Discovery Call Recording.mp3",
    "status": "processing | ready | failed",
    "type": "asset | intel",
    "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "run_id": "run_xyz789"
}

Rate limits: Organization-wide and per-API-key limits apply. Uploads may consume a separate usage quota.

Deal Identification

You can identify the deal using one of three methods:

Parameter	Description
`deal_id`	Hindsight’s internal deal ID
`salesforce_id`	Salesforce Opportunity ID (e.g., `006xxxxxxxxxxxx`)
`hubspot_id`	HubSpot Deal ID

Source Options

The source field determines the icon displayed and helps with document organization:

Source	Description
`gong`	Gong call recordings
`clari`	Clari
`fathom`	Fathom AI
`fireflies`	Fireflies.ai
`avoma`	Avoma
`outreach`	Outreach
`gmail`	Gmail
`Salesforce`	Salesforce
`Hubspot`	HubSpot
`api`	API upload

Supported File Types

Category	Formats	Notes
Documents	PDF, DOCX, PPTX, XLSX, MD, TXT	Parsed and chunked for search
Audio	MP3, WAV, M4A	Automatically transcribed via Whisper
Video	MP4	Automatically transcribed via Whisper

curl -X POST https://app.usehindsight.com/api/v1/deals/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "Discovery Call Recording.mp3",
    "file_url": "https://example.com/recording.mp3",
    "content_type": "audio/mpeg",
    "salesforce_id": "006xxxxxxxxxxxx",
    "source": "gong"
  }'

const response = await fetch('https://app.usehindsight.com/api/v1/deals/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    file_name: 'Discovery Call Recording.mp3',
    file_url: 'https://example.com/recording.mp3',
    content_type: 'audio/mpeg',
    salesforce_id: '006xxxxxxxxxxxx',
    source: 'gong'
  })
});

const data = await response.json();
console.log(`Document uploaded: ${data.document.id}`);
console.log(`Processing run: ${data.run_id}`);

import requests

response = requests.post(
    'https://app.usehindsight.com/api/v1/deals/documents',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'file_name': 'Discovery Call Recording.mp3',
        'file_url': 'https://example.com/recording.mp3',
        'content_type': 'audio/mpeg',
        'salesforce_id': '006xxxxxxxxxxxx',
        'source': 'gong'
    }
)

data = response.json()
print(f"Document uploaded: {data['document']['id']}")
print(f"Processing run: {data['run_id']}")

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

multipart/form-data

file_name

string

required

Name of the file

Example:

"Discovery Call Notes.pdf"

content_type

string

required

MIME type of the file

Example:

"application/pdf"

file_url

string<uri>

URL to download the file from (provide either file_url or file)

file

Binary file content (provide either file or file_url)

deal_id

string

Hindsight deal ID (provide one of deal_id, salesforce_id, or hubspot_id)

Example:

"deal_123"

salesforce_id

string

Salesforce Opportunity ID

Example:

"006xxxxxxxxxxxx"

hubspot_id

string

HubSpot Deal ID

Example:

"12345678"

source

enum<string>

Source application where the document originated

Available options:

gong,

clari,

fathom,

fireflies,

avoma,

outreach,

gmail,

Salesforce,

Hubspot,

api

Example:

"gong"

Response

Document upload initiated

document

object

Show child attributes

run_id

string

ID to track the document processing run

Example:

"run_xyz789"

curl -X POST https://app.usehindsight.com/api/v1/deals/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "Discovery Call Recording.mp3",
    "file_url": "https://example.com/recording.mp3",
    "content_type": "audio/mpeg",
    "salesforce_id": "006xxxxxxxxxxxx",
    "source": "gong"
  }'

const response = await fetch('https://app.usehindsight.com/api/v1/deals/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    file_name: 'Discovery Call Recording.mp3',
    file_url: 'https://example.com/recording.mp3',
    content_type: 'audio/mpeg',
    salesforce_id: '006xxxxxxxxxxxx',
    source: 'gong'
  })
});

const data = await response.json();
console.log(`Document uploaded: ${data.document.id}`);
console.log(`Processing run: ${data.run_id}`);

import requests

response = requests.post(
    'https://app.usehindsight.com/api/v1/deals/documents',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'file_name': 'Discovery Call Recording.mp3',
        'file_url': 'https://example.com/recording.mp3',
        'content_type': 'audio/mpeg',
        'salesforce_id': '006xxxxxxxxxxxx',
        'source': 'gong'
    }
)

data = response.json()
print(f"Document uploaded: {data['document']['id']}")
print(f"Processing run: {data['run_id']}")

{
  "document": {
    "id": "doc_abc123",
    "file_name": "Competitor X Pricing Guide.pdf",
    "status": "processing",
    "type": "asset",
    "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "run_id": "run_xyz789"
}

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

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

{
  "error": {
    "code": "not_found",
    "message": "Deal with the specified ID was not found"
  }
}

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

Deal Identification

Source Options

Supported File Types

Authorizations

Body

Response

​Deal Identification

​Source Options

​Supported File Types

Authorizations

Body

Response

Deal Identification

Source Options

Supported File Types