---
title: "Create an interview request"
method: POST
path: "/interviews"
tags: ["Interviews"]
---

# Create an interview request

`POST /interviews`

## Request

- Base URL: `https://app.usehindsight.com/api/v1`
- URL: `https://app.usehindsight.com/api/v1/interviews`
- Auth: HTTP bearer

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.

## Request body

- CreateInterviewRequest
  - `contact_email` string, email: Email address of the person to interview. Required. Buyer contacts are upserted; seller requests use this as the internal respondent.
  - `contact_name` string: Full name of the person to interview. Used to create or update a buyer contact record.
  - `contact_context` union: 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.
    - string
    - object
  - `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.
  - `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.
  - `deal_id` string: Hindsight deal ID to associate this interview with. The deal must belong to your organization. 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': 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`.
  - `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").

## Response `201`

Interview request created

- CreateInterviewResponse
  - `interview_request_id` integer: ID of the created interview request.
  - `contact_id` string, nullable: ID of the upserted buyer contact record, or null for seller requests.
  - `deal_id` string, nullable: Resolved Hindsight deal ID, or null.
  - `salesforce_opportunity_id` string, nullable: Salesforce Opportunity ID used to resolve the deal, or null.
  - `respondent_type` 'buyer' | 'seller': Audience for the created interview request.
  - `survey_url` string, nullable: Direct link to the survey for this contact. Share this link manually if not using a sequence.
  - `survey_token` string, nullable: Raw token used in the survey URL.
  - `status` 'created' | 'sent': `created` — interview request created, no outreach sent (link-only path). `sent` — contact enrolled in sequence, outreach queued.

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - invalid or missing API key
- `429`: Too many requests - rate limit or applicable usage quota exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/usehindsight/apis/hindsight-api.md) - [All operations](https://skmtc.dev/usehindsight/apis/hindsight-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usehindsight/apis/hindsight-api/revisions/97371a7da857?raw)