REST API

Create Interview Request

Creates an interview request. Buyer requests upsert the contact by email. When a sequence_id is provided, the buyer 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. Set respondent_type to seller to create an internal, link-only seller request with no contact creation, email, Slack, or sequence outreach.

POST

interviews

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

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",
    "interview_type_id": "type_abc123",
    "objective": "Understand why we lost this deal to Competitor X"
  }'

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": "Alex Rep",
    "interview_type_id": "seller_debrief_type_abc123",
    "salesforce_opportunity_id": "006xx000001ABCdAAO",
    "respondent_type": "seller",
    "objective": "Capture the seller perspective on this closed deal."
  }'

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}`);

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']}")

{
  "interview_request_id": 4821,
  "contact_id": "contact_abc123",
  "deal_id": "deal_xyz789",
  "salesforce_opportunity_id": null,
  "respondent_type": "buyer",
  "survey_url": "https://app.usehindsight.com/survey?token=tok_xyz",
  "survey_token": "tok_xyz",
  "status": "sent"
}

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

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

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

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; mutually exclusive with salesforce_opportunity_id
  "salesforce_opportunity_id": "006...",    // optional; resolves a synced Hindsight deal
  "respondent_type": "buyer",               // optional: "buyer" (default) or "seller"
  "objective": "Understand loss to Competitor X"  // optional
}

201 Response:
{
  "interview_request_id": 4821,
  "contact_id": "contact_abc123",
  "deal_id": "deal_xyz789",
  "salesforce_opportunity_id": "006...",
  "respondent_type": "buyer",
  "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: Organization-wide and per-API-key limits apply. Interview actions may consume a separate usage quota.

Overview

Use this endpoint to programmatically trigger win-loss interviews. There are three 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.
Seller path (respondent_type: "seller") — Creates an internal, link-only seller debrief. No contact is created, and the API does not send email, Slack messages, or sequence outreach.

Buyer 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. Seller requests use the supplied email as the internal respondent and return contact_id: null.

Request Parameters

Required

You must provide either sequence_id or interview_type_id.

Parameter	Type	Description
`contact_email`	string	Email of the person to interview. For buyers, a contact is created or updated; for sellers, it identifies the internal respondent.
`sequence_id`	string	ID of the outreach sequence to enroll a buyer contact in. Paige sends the interview email automatically. Not supported for seller interviews.
`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 person to interview. Used to create or update a buyer contact record.
`contact_context`	string \| object	Background context about a buyer contact, passed to Paige when conducting the interview. Accepts a plain string or a JSON object (serialized automatically). Stored in the buyer contact’s notes and included in every interview prompt.
`deal_id`	string	Hindsight deal ID to associate the interview with. Mutually exclusive with `salesforce_opportunity_id`.
`salesforce_opportunity_id`	string	Salesforce Opportunity ID for an already-synced deal. Hindsight resolves it using the organization-scoped `deals.salesforce_id` field. Mutually exclusive with `deal_id`.
`respondent_type`	`"buyer"` \| `"seller"`	Defaults to `"buyer"`. Use `"seller"` to create an internal, link-only seller request (`external: false`). Seller requests cannot include `sequence_id`.
`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
Salesforce Opportunity IDs — Salesforce Opportunity.Id; the deal must already be synced to Hindsight

Contact Context

The contact_context field is the primary way to give Paige background on a buyer. This context is stored in the buyer 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 \| null	ID of the upserted buyer contact record; `null` for sellers.
`deal_id`	string \| null	Resolved Hindsight deal ID, or null.
`salesforce_opportunity_id`	string \| null	Salesforce Opportunity ID used to resolve the deal, or `null` when `deal_id` was used or no deal was supplied.
`respondent_type`	`"buyer"` \| `"seller"`	The audience for this interview request.
`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

Organization-wide and per-API-key limits apply. Interview actions may consume a separate usage quota. Handle 429 Too Many Requests using the current response headers:

Header	Description
`X-RateLimit-Limit`	Requests allowed in the active response limit 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"
  }'

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",
    "interview_type_id": "type_abc123",
    "objective": "Understand why we lost this deal to Competitor X"
  }'

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": "Alex Rep",
    "interview_type_id": "seller_debrief_type_abc123",
    "salesforce_opportunity_id": "006xx000001ABCdAAO",
    "respondent_type": "seller",
    "objective": "Capture the seller perspective on this closed deal."
  }'

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}`);

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. For already-synced Salesforce opportunities, pass salesforce_opportunity_id instead of maintaining a separate Hindsight deal-ID mapping. Pass only one of salesforce_opportunity_id and deal_id.

Salesforce-only seller debriefs

Use a Salesforce Flow or outbound callout to invoke the seller path on Closed Won or Closed Lost. Set respondent_type to "seller", pass the opportunity owner’s email as contact_email, and store the returned survey_url on the Opportunity. This path creates an internal request without Slack or email delivery.

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 or invalid field; an unknown `sequence_id`, `interview_type_id`, `deal_id`, or `salesforce_opportunity_id`; both deal identifiers; or a seller request with `sequence_id`.
`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 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

contact_email

string<email>

Email address of the person to interview. Required. Buyer contacts are upserted; seller requests use this as the internal respondent.

Example:

"[email protected]"

contact_name

string

Full name of the person to interview. Used to create or update a buyer contact record.

Example:

"Jane Smith"

contact_context

Unstructured context about a buyer 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 buyer contact's notes field and included in every interview prompt for that 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. Mutually exclusive with salesforce_opportunity_id.

Example:

"deal_xyz789"

salesforce_opportunity_id

string

Salesforce Opportunity ID for an already-synced deal. Hindsight resolves it using the organization-scoped deals.salesforce_id field. Mutually exclusive with deal_id.

Example:

"006xx000001ABCdAAO"

respondent_type

enum<string>

default:buyer

Audience for the interview. buyer upserts an external contact and supports sequences. seller creates an internal, link-only request and cannot be used with sequence_id.

Available options:

buyer,

seller

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 | null

ID of the upserted buyer contact record, or null for seller requests.

Example:

"contact_abc123"

deal_id

string | null

Resolved Hindsight deal ID, or null.

Example:

"deal_xyz789"

salesforce_opportunity_id

string | null

Salesforce Opportunity ID used to resolve the deal, or null.

Example:

"006xx000001ABCdAAO"

respondent_type

enum<string>

Audience for the created interview request.

Available options:

buyer,

seller

Example:

"buyer"

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"

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

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",
    "interview_type_id": "type_abc123",
    "objective": "Understand why we lost this deal to Competitor X"
  }'

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": "Alex Rep",
    "interview_type_id": "seller_debrief_type_abc123",
    "salesforce_opportunity_id": "006xx000001ABCdAAO",
    "respondent_type": "seller",
    "objective": "Capture the seller perspective on this closed deal."
  }'

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}`);

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']}")

{
  "interview_request_id": 4821,
  "contact_id": "contact_abc123",
  "deal_id": "deal_xyz789",
  "salesforce_opportunity_id": null,
  "respondent_type": "buyer",
  "survey_url": "https://app.usehindsight.com/survey?token=tok_xyz",
  "survey_token": "tok_xyz",
  "status": "sent"
}

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

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

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

Create Interview Request

Overview

Request Parameters

Required

Optional

Finding IDs

Contact Context

Response

Rate Limits

Examples

Common Patterns

Trigger on CRM deal close

Salesforce-only seller debriefs

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

​Salesforce-only seller debriefs

​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

Salesforce-only seller debriefs

Manual outreach with custom delivery

Enriching contact context over time

Error Responses