Create Interview Request - Hindsight Docs

Copy for AI context

POST https://app.usehindsight.com/api/v1/interviews
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body:
{
  "contact_email": "[email protected]",          // 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 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:

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

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

curl -X POST "https://app.usehindsight.com/api/v1/interviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "[email protected]",
    "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"
  }'

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.

{
  "error": {
    "code": "bad_request",
    "message": "sequence_id not found"
  }
}

​Overview

​Request Parameters

​Required

​Optional

​Finding IDs

​Contact Context

​Response

​Rate Limits

​Examples

​Common Patterns

​Trigger on CRM deal close

​Manual outreach with custom delivery

​Enriching contact context over time

​Error Responses