> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehindsight.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Interview Request
> Creates an interview request for a contact. Upserts the contact by email if they don't exist yet.
When a `sequence_id` is provided, the contact is enrolled in the sequence and Hindsight's
scheduling agent handles outreach automatically. When only `interview_type_id` is provided,
the request is created and the survey link is returned without any outreach.
```text theme={null}
POST https://app.usehindsight.com/api/v1/interviews
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body:
{
"contact_email": "jane@acme.com", // required
"contact_name": "Jane Smith", // optional — creates/updates contact
"contact_context": { // optional — stored as contact notes, used by Paige
"title": "VP of Engineering",
"use_case": "Evaluating us for CI/CD automation"
},
"sequence_id": "seq_abc123", // required if no interview_type_id
"interview_type_id": "type_abc123", // required if no sequence_id
"deal_id": "deal_xyz789", // optional
"objective": "Understand loss to Competitor X" // optional
}
201 Response:
{
"interview_request_id": 4821,
"contact_id": "contact_abc123",
"deal_id": "deal_xyz789",
"survey_url": "https://app.usehindsight.com/survey?token=tok_xyz",
"survey_token": "tok_xyz",
"status": "sent" // "sent" = enrolled in sequence | "created" = link only
}
Rate limits: 60 req/min (Essentials), 300 req/min (Growth), 1,000 req/min (Enterprise)
```
## Overview
Use this endpoint to programmatically trigger win-loss interviews for your contacts. Two paths:
* **Sequence path** (`sequence_id`) — Hindsight enrolls the contact and Paige handles email outreach automatically. The interview type, email template, and scheduling logic are inherited from the sequence.
* **Link-only path** (`interview_type_id`) — Creates the interview request and returns a survey link. No email is sent; you control delivery.
Contacts are upserted by email — if the contact already exists in your org, their record is updated with any new name or context you provide.
## Request Parameters
### Required
You must provide either `sequence_id` or `interview_type_id`.
| Parameter | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `contact_email` | string | Email of the contact to interview. The contact is created if they don't exist, or updated if they do. |
| `sequence_id` | string | ID of the outreach sequence to enroll the contact in. Paige sends the interview email automatically. |
| `interview_type_id` | string | ID of the interview type (e.g. win-loss buyer, NPS). Use this for link-only requests where you handle delivery yourself. |
### Optional
| Parameter | Type | Description |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contact_name` | string | Full name of the contact. Used to create or update the contact record. |
| `contact_context` | string \| object | Background context about the contact, passed to Paige when conducting the interview. Accepts a plain string or a JSON object (serialized automatically). Stored in the contact's notes and included in every interview prompt. |
| `deal_id` | string | Hindsight deal ID to associate the interview with. |
| `objective` | string | Custom goal for this interview. Paige uses this as additional context (e.g. "Understand why we lost to Competitor X on pricing"). |
### Finding IDs
* **Sequence IDs** — Settings → Sequences in your Hindsight dashboard
* **Interview type IDs** — Settings → Interview Types
* **Deal IDs** — Use the [Get Deals](/api-reference/get-deals) endpoint or find them in the dashboard URL
## Contact Context
The `contact_context` field is the primary way to give Paige background on who she's interviewing. This context is stored in the contact's notes field and used in every interview prompt for that contact.
Pass anything relevant — role, company details, the deal they were involved in, why you're reaching out, or any other signal that helps Paige have a more informed conversation:
```json theme={null}
{
"contact_context": {
"title": "VP of Engineering",
"company_size": "500-1000 employees",
"use_case": "Evaluating us for CI/CD pipeline automation",
"evaluation_stage": "Completed a 30-day POC",
"primary_concern": "Integration complexity with existing toolchain"
}
}
```
You can also pass a plain string:
```json theme={null}
{
"contact_context": "Jane led the technical evaluation at Acme. She was enthusiastic about the product but raised concerns about our Jira integration."
}
```
## Response
| Field | Type | Description |
| ---------------------- | ----------------------- | --------------------------------------------------------------------------- |
| `interview_request_id` | integer | ID of the created interview request. |
| `contact_id` | string | ID of the upserted contact record. |
| `deal_id` | string \| null | Deal ID from the request, or null. |
| `survey_url` | string \| null | Direct link to the survey. Share this if you're handling delivery yourself. |
| `survey_token` | string \| null | Raw token used in the survey URL. |
| `status` | `"created"` \| `"sent"` | `sent` when enrolled in a sequence; `created` for link-only requests. |
## Rate Limits
| Plan | Requests per Minute |
| ---------- | ------------------- |
| Essentials | 60 |
| Growth | 300 |
| Enterprise | 1,000 |
Rate limit headers are included on every response:
| Header | Description |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit` | Your plan's request limit per window |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
## Examples
```bash Sequence enrollment (with outreach) theme={null}
curl -X POST "https://app.usehindsight.com/api/v1/interviews" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_email": "jane@acme.com",
"contact_name": "Jane Smith",
"contact_context": {
"title": "VP of Engineering",
"use_case": "Evaluating us for CI/CD pipeline automation"
},
"sequence_id": "seq_abc123",
"deal_id": "deal_xyz789"
}'
```
```bash Link-only (no outreach) theme={null}
curl -X POST "https://app.usehindsight.com/api/v1/interviews" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_email": "jane@acme.com",
"contact_name": "Jane Smith",
"interview_type_id": "type_abc123",
"objective": "Understand why we lost this deal to Competitor X"
}'
```
```javascript Node.js - Trigger interview on deal close theme={null}
const response = await fetch('https://app.usehindsight.com/api/v1/interviews', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HINDSIGHT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
contact_email: deal.buyer_email,
contact_name: deal.buyer_name,
contact_context: {
title: deal.buyer_title,
company: deal.account_name,
deal_value: deal.amount,
close_reason: deal.close_reason,
},
sequence_id: process.env.HINDSIGHT_WL_SEQUENCE_ID,
deal_id: deal.hindsight_id,
objective: `Win-loss analysis for ${deal.name}`,
}),
});
const { interview_request_id, survey_url, status } = await response.json();
console.log(`Interview ${status}: ${survey_url}`);
```
```python Python - Bulk trigger from CRM export theme={null}
import requests
import os
API_KEY = os.environ['HINDSIGHT_API_KEY']
SEQUENCE_ID = os.environ['HINDSIGHT_WL_SEQUENCE_ID']
def create_interview(contact_email, contact_name, deal_id=None, context=None):
response = requests.post(
'https://app.usehindsight.com/api/v1/interviews',
headers={'Authorization': f'Bearer {API_KEY}'},
json={
'contact_email': contact_email,
'contact_name': contact_name,
'contact_context': context,
'sequence_id': SEQUENCE_ID,
'deal_id': deal_id,
}
)
response.raise_for_status()
return response.json()
# Trigger interviews for recently closed deals
closed_deals = fetch_closed_deals_from_crm()
for deal in closed_deals:
result = create_interview(
contact_email=deal['buyer_email'],
contact_name=deal['buyer_name'],
deal_id=deal['hindsight_id'],
context={
'title': deal['buyer_title'],
'company': deal['account_name'],
'deal_size': deal['amount'],
}
)
print(f"{deal['name']}: {result['status']} — {result['survey_url']}")
```
## Common Patterns
### Trigger on CRM deal close
Connect Hindsight to your CRM via webhook or scheduled job to automatically send win-loss interviews whenever a deal closes. Pass the deal context so Paige has background on what was evaluated.
### Manual outreach with custom delivery
Use `interview_type_id` (no `sequence_id`) to get a survey link you can embed in your own email or send via your CRM. This is useful when you want full control over messaging or timing.
### Enriching contact context over time
If you call this endpoint multiple times for the same contact, `contact_context` overwrites the existing notes. To preserve prior context, read the contact's current notes first and merge before sending.
## Error Responses
| Code | Description |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| `bad_request` | Missing required field, or `sequence_id` / `interview_type_id` / `deal_id` not found in your org. |
| `unauthorized` | Invalid or missing API key. |
| `rate_limit_exceeded` | Too many requests. Check `X-RateLimit-Reset` and retry after. |
| `internal_error` | Failed to create the contact record. |
```json theme={null}
{
"error": {
"code": "bad_request",
"message": "sequence_id not found"
}
}
```
## OpenAPI
````yaml POST /interviews
openapi: 3.1.0
info:
title: Hindsight API
description: >
Integrate Hindsight competitive intelligence, win-loss insights, and deal
data into your applications.
## Authentication
All API requests require a Bearer token in the Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```
Get your API key from the [Hindsight
dashboard](https://app.usehindsight.com/settings/keys).
## Rate Limits
API and MCP requests are rate-limited per organization. The per-minute rate
limit is
shared across API and MCP traffic and uses a 60-second sliding window.
Direct tool
calls also consume a monthly usage bucket; `select-deal` and `get-deal`
consume one
read each from the shared reads bucket after authorization and validation
succeed.
| Plan | Per Minute | Per Month |
|------|-----------|----------|
| Essentials | 10 | 10,000 |
| Growth | 60 | 30,000 |
| Enterprise | 300 | 100,000 |
Successful direct-tool responses include `X-RateLimit-Limit`,
`X-RateLimit-Remaining`,
`X-RateLimit-Reset` (Unix milliseconds), `X-Usage-Used`, `X-Usage-Limit`,
`X-Usage-Remaining`, and `X-Usage-Period-End`. When a limit is exceeded, the
API
returns a `429` response with the relevant headers.
version: 1.0.0
contact:
name: Hindsight Support
url: https://usehindsight.com/support
email: support@hindsight.com
servers:
- url: https://app.usehindsight.com/api/v1
description: Production server
security:
- bearerAuth: []
tags:
- name: Chat
description: AI-powered chat completions with competitive intelligence
- name: Deals
description: Access and export deal data
- name: Documents
description: Upload and manage documents
- name: Interviews
description: Create and manage win-loss interview requests
- name: Tools
description: Structured Hindsight tool calls for application-controlled workflows
paths:
/interviews:
post:
tags:
- Interviews
summary: Create an interview request
description: >
Creates an interview request for a contact. Upserts the contact by email
if they don't exist yet.
When a `sequence_id` is provided, the contact is enrolled in the
sequence and Hindsight's
scheduling agent handles outreach automatically. When only
`interview_type_id` is provided,
the request is created and the survey link is returned without any
outreach.
operationId: createInterview
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInterviewRequest'
examples:
withSequence:
summary: Enroll in a sequence (with outreach)
value:
contact_email: jane@acme.com
contact_name: Jane Smith
contact_context:
title: VP of Engineering
company: Acme Corp
use_case: Evaluating us for CI/CD pipeline automation
sequence_id: seq_abc123
deal_id: deal_xyz789
linkOnly:
summary: Create survey link only (no outreach)
value:
contact_email: jane@acme.com
contact_name: Jane Smith
interview_type_id: type_abc123
objective: Understand why we lost this deal to Competitor X
responses:
'201':
description: Interview request created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInterviewResponse'
example:
interview_request_id: 4821
contact_id: contact_abc123
deal_id: deal_xyz789
survey_url: https://app.usehindsight.com/survey?token=tok_xyz
survey_token: tok_xyz
status: sent
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
CreateInterviewRequest:
type: object
required: []
properties:
contact_email:
type: string
format: email
description: >-
Email address of the contact. Required. The contact is upserted —
created if new, updated if existing.
example: jane@acme.com
contact_name:
type: string
description: >-
Full name of the contact. Used to create or update the contact
record.
example: Jane Smith
contact_context:
oneOf:
- type: string
- type: object
additionalProperties: true
description: >
Unstructured context about this contact — passed to Paige as
background information when conducting
the interview. Can be a plain string or a JSON object; objects are
serialized automatically.
Stored in the contact's notes field and included in every interview
prompt for this contact.
example:
title: VP of Engineering
use_case: Evaluating us for CI/CD pipeline automation
evaluation_stage: POC completed
interview_type_id:
type: string
description: >
ID of the interview type to use (e.g. win-loss buyer, NPS). Required
if `sequence_id` is not provided.
Find interview type IDs in your Hindsight dashboard under Settings →
Interview Types.
example: type_abc123
sequence_id:
type: string
description: >
ID of an outreach sequence. When provided, the contact is enrolled
in the sequence and
Hindsight's scheduling agent handles email delivery automatically.
The interview type is
inherited from the sequence. Required if `interview_type_id` is not
provided.
example: seq_abc123
deal_id:
type: string
description: >
Hindsight deal ID to associate this interview with. The deal must
belong to your organization.
example: deal_xyz789
objective:
type: string
description: >
Custom goal for this specific interview. Paige uses this as
additional context when
conducting the interview (e.g. "Understand why we lost to Competitor
X on pricing").
example: Understand why we lost this deal to Competitor X
CreateInterviewResponse:
type: object
properties:
interview_request_id:
type: integer
description: ID of the created interview request.
example: 4821
contact_id:
type: string
description: ID of the upserted contact record.
example: contact_abc123
deal_id:
type: string
nullable: true
description: Deal ID passed in the request, or null.
example: deal_xyz789
survey_url:
type: string
nullable: true
description: >-
Direct link to the survey for this contact. Share this link manually
if not using a sequence.
example: https://app.usehindsight.com/survey?token=tok_xyz
survey_token:
type: string
nullable: true
description: Raw token used in the survey URL.
example: tok_xyz
status:
type: string
enum:
- created
- sent
description: >
`created` — interview request created, no outreach sent (link-only
path).
`sent` — contact enrolled in sequence, outreach queued.
example: sent
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Error code
example: unauthorized
message:
type: string
description: Human-readable error message
example: Invalid API key
details:
type: object
description: Additional error details
additionalProperties: true
responses:
BadRequest:
description: Bad request - invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: bad_request
message: Invalid parameters
details:
missing_fields:
- file_name
Unauthorized:
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unauthorized
message: Invalid API key
RateLimitExceeded:
description: >-
Too many requests - per-minute rate limit or monthly usage quota
exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: rate_limit_exceeded
message: >-
Rate limit exceeded. Please retry after the reset time in the
response headers.
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Requests allowed in the current 60-second window.
X-RateLimit-Remaining:
schema:
type: integer
description: Requests remaining in the current 60-second window.
X-RateLimit-Reset:
schema:
type: integer
format: int64
description: Unix timestamp in milliseconds when the rate-limit window resets.
X-Usage-Used:
schema:
type: integer
description: Requests consumed from the applicable monthly bucket.
X-Usage-Limit:
schema:
type: integer
description: Monthly allowance for the applicable usage bucket.
X-Usage-Remaining:
schema:
type: integer
description: Requests remaining in the applicable monthly usage bucket.
X-Usage-Period-End:
schema:
type: string
format: date-time
description: ISO timestamp when the monthly usage period resets.
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: internal_error
message: An unexpected error occurred
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key from Hindsight dashboard
````