---
title: "Start interview previews"
method: POST
path: "/api/v1/research/interview-previews/start"
tags: ["research"]
---

# Start interview previews

`POST /api/v1/research/interview-previews/start`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/research/interview-previews/start`
- Auth: OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Run one sample interview of a draft Research study: one customer twin of a business profile answers the edited questions once, skipping computer tasks. For an organization already subscribed to Point11 Analytics; the sample is unbilled and never appears in campaign lists or results. Returns the sample's run; read its transcript with research_interview_previews_get_v3.

## Headers

- `Point11-Organization` string, uuid
- `Idempotency-Key` string, uuid, required

## Request body

- ResearchInterviewPreviewsStartRequest
  - `campaignName` string, required: The sample's name, e.g. "Brand health sample interview".
  - `businessProfileId` string, uuid, required: The business profile whose customer twin is interviewed.
  - `targetedCustomerIds` string[], required: Exactly one customer twin of the profile to interview.
  - `questions` ResearchQuestionsItem[], required: The whole edited instrument. The sample skips computer tasks, so the rest must follow a valid route and hold a question to ask. Acceptable use screens each question's prompt, a task's success criteria and website starting site, and each branch rule's meaning whole, so each is at most 2,000 characters (titles, options and file names are shorter by their own bounds), and the study's screened text is at most 160 KiB; nothing is truncated.
    - union
      - object
        - `id` string, required
        - `title` string, required
        - `prompt` string, required
        - `flow` union
          - object
            - `kind` 'goto', required
            - `target` union, required
              - …
          - object
            - `kind` 'branch', required
            - `rules` object[], required
              - …
            - `otherwise` union, required
              - …
        - `attachment` object
          - `artifactId` string, required
          - `filename` string, required
          - `mediaType` 'image/png' | 'image/jpeg' | 'image/webp' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/csv' | 'video/mp4' | 'video/webm' | 'audio/mpeg' | 'audio/wav', required
          - `byteLength` integer, required
        - `stimulusItemId` string
        - `blind` true
        - `shape` 'open_ended', required
      - object
        - `id` string, required
        - `title` string, required
        - `prompt` string, required
        - `flow` union
          - object
            - `kind` 'goto', required
            - `target` union, required
              - …
          - object
            - `kind` 'branch', required
            - `rules` object[], required
              - …
            - `otherwise` union, required
              - …
        - `attachment` object
          - `artifactId` string, required
          - `filename` string, required
          - `mediaType` 'image/png' | 'image/jpeg' | 'image/webp' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/csv' | 'video/mp4' | 'video/webm' | 'audio/mpeg' | 'audio/wav', required
          - `byteLength` integer, required
        - `stimulusItemId` string
        - `blind` true
        - `shape` 'closed_ended' | 'multi_select' | 'rank' | 'matrix' | 'scale', required
        - `options` string[], required
        - `maxSelections` integer
        - `unaided` true
      - object
        - `id` string, required
        - `title` string, required
        - `prompt` string, required
        - `flow` union
          - object
            - `kind` 'goto', required
            - `target` union, required
              - …
          - object
            - `kind` 'branch', required
            - `rules` object[], required
              - …
            - `otherwise` union, required
              - …
        - `attachment` object
          - `artifactId` string, required
          - `filename` string, required
          - `mediaType` 'image/png' | 'image/jpeg' | 'image/webp' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/csv' | 'video/mp4' | 'video/webm' | 'audio/mpeg' | 'audio/wav', required
          - `byteLength` integer, required
        - `stimulusItemId` string
        - `blind` true
        - `shape` 'computer_task', required
        - `targets` union[], required
          - union
            - object
              - …
            - object
              - …
        - `successCriteria` string, required
  - `playbookKey` 'ad_copy' | 'brand_health' | 'offers' | 'pricing' | 'product' | 'product_launch' | 'sales' | 'custom' | 'product_roadmap', required
  - `stimulus` union, required: The study's material. Acceptable use screens a Custom study's content whole, so it is at most 2,000 characters.
    - object
      - `version` 'research-stimulus.v1', required
      - `kind` 'brand', required
      - `title` string
      - `brand` string, required
      - `category` string
      - `competitors` string[], required
      - `startUrl` string, uri
      - `shownList` string[]
    - object
      - `version` 'research-stimulus.v1', required
      - `kind` 'copy', required
      - `title` string
      - `copies` object[], required
        - `id` string, required
        - `label` string
        - `body` string, required
    - ResearchStimulusVariant
      - `version` 'research-stimulus.v1', required
      - `kind` 'ads', required
      - `title` string
      - `format` 'full_ad' | 'headline' | 'tagline' | 'product_name' | 'email_subject' | 'social_post'
      - `placement` string
      - `ads` object[], required
        - `id` string, required
        - `headline` string, required
        - `body` string
        - `callToAction` string
        - `landingUrl` string, uri
        - `intendedTakeaway` string
    - object
      - `version` 'research-stimulus.v1', required
      - `kind` 'concept', required
      - `title` string
      - `concepts` object[], required
        - `id` string, required
        - `title` string, required
        - `description` string, required
        - `assetRefs` string[]
        - `prototypeUrl` string, uri
        - `buyerGoal` string
    - ResearchStimulusVariant2
      - `version` 'research-stimulus.v1', required
      - `kind` 'offer_set', required
      - `title` string
      - `offers` object[], required
        - `id` string, required
        - `title` string, required
        - `description` string, required
        - `terms` string
      - `category` string
      - `liveOffer` object
        - `offerId` string, required
        - `url` string, uri, required
    - ResearchStimulusVariant3
      - `version` 'research-stimulus.v1', required
      - `kind` 'price_ladder', required
      - `title` string, required
      - `description` string
      - `currency` string, required
      - `billingUnit` 'one_time' | 'per_month' | 'per_year' | 'per_seat_per_month'
      - `prices` object[], required
        - `id` string, required
        - `amountMinor` integer, required
        - `label` string
      - `plannedPriceId` string
      - `category` string
      - `alternatives` object[]
        - `name` string, required
        - `amountMinor` integer, required
      - `plans` string[]
      - `pricingPageUrl` string, uri
    - object
      - `version` 'research-stimulus.v1', required
      - `kind` 'task', required
      - `title` string, required
      - `instructions` string, required
      - `destinationUrl` string, uri
      - `problem` string
      - `keyMessage` string
    - object
      - `version` 'research-stimulus.v1', required
      - `kind` 'custom', required
      - `title` string
      - `content` string, required
      - `assetRefs` string[]
      - `private` true
    - ResearchStimulusVariant4
      - `version` 'research-stimulus.v1', required
      - `kind` 'features', required
      - `title` string
      - `job` string, required
      - `productName` string, required
      - `features` object[], required
        - `id` string, required
        - `name` string, required
        - `description` string, required
      - `productTask` object
        - `startUrl` string, uri, required
        - `successCriteria` string, required
  - `researchFocus` string: The study's research focus, screened whole by acceptable use: at most 2,000 characters.
  - `assumptions` string[]: Customer assumptions: statements every respondent answers as true of themselves for this study only, beside their own profile, in order; absent or empty when the study states none. Acceptable use screens each whole, so each is at most 2,000 characters, and none is empty.

## Response `202`

Accepted: the durable run started. Follow it with `GET /api/v1/platform/runs-v2/{id}`.

- ResearchInterviewPreviewsStartResponse
  - `runId` string, uuid, required: The sample's run; read it with research.interview-previews.get.v2.
  - `status` 'workflow_started' | 'encounter_coordination_required', required: How the sample's run starts.
  - `campaignId` string, uuid, required: The sample's own campaign, never listed or reported.

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `402`: Billing refused the write: the code names the reason and `details.reason` carries it.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/36a84c7aca11?raw)