USusehindsight
Interviews

Create an 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

Request

  • Base URL
    https://app.usehindsight.com/api/v1
  • Auth
    HTTP bearer

Request body

contact_emailstring email

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

contact_namestring

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

interview_type_idstring

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_idstring

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_idstring

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

salesforce_opportunity_idstring

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.

objectivestring

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 request

{
  "contact_email": "jane@acme.com",
  "contact_name": "Jane Smith",
  "interview_type_id": "type_abc123",
  "sequence_id": "seq_abc123",
  "deal_id": "deal_xyz789",
  "salesforce_opportunity_id": "006xx000001ABCdAAO",
  "objective": "Understand why we lost this deal to Competitor X"
}

Response

Interview request created

interview_request_idinteger

ID of the created interview request.

contact_idstring nullable

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

deal_idstring nullable

Resolved Hindsight deal ID, or null.

salesforce_opportunity_idstring nullable

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

respondent_type'buyer' | 'seller'

Audience for the created interview request.

survey_urlstring nullable

Direct link to the survey for this contact. Share this link manually if not using a sequence.

survey_tokenstring 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.

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.