Create Interview Request

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

Authorizations

Authorization

string

header

required

API key from Hindsight dashboard

Body

application/json

contact_email

string<email>

Email address of the contact. Required. The contact is upserted — created if new, updated if existing.

Example:

"[email protected]"

contact_name

string

Full name of the contact. Used to create or update the contact record.

Example:

"Jane Smith"

contact_context

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

string

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

string

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

string

Hindsight deal ID to associate this interview with. The deal must belong to your organization.

Example:

"deal_xyz789"

objective

string

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"

Response

Interview request created

interview_request_id

integer

ID of the created interview request.

Example:

4821

contact_id

string

ID of the upserted contact record.

Example:

"contact_abc123"

deal_id

string | null

Deal ID passed in the request, or null.

Example:

"deal_xyz789"

survey_url

string | null

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

string | null

Raw token used in the survey URL.

Example:

"tok_xyz"

status

enum<string>

created — interview request created, no outreach sent (link-only path). sent — contact enrolled in sequence, outreach queued.

Available options:

created,

sent

Example:

"sent"

Overview

MCP

Endpoints

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

Authorizations

Body

Response

Overview

MCP

Endpoints

Documentation Index

​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

Authorizations

Body

Response

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