---
title: "Launch campaigns"
method: POST
path: "/api/v1/research/campaigns/launch"
tags: ["research"]
---

# Launch campaigns

`POST /api/v1/research/campaigns/launch`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/research/campaigns/launch`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Start a Research study on a business profile's customers, once or on a weekly or monthly quota, for an organization already subscribed to Point11 Analytics. Returns the campaign and the billing run of its first interviews; an organization without an active subscription is refused, since subscribing happens only in the dashboard. Every interview is billed as delivered usage against the organization's allowance, then approved overage; a weekly or monthly study consumes allowance on every run.

## Headers

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

## Request body

- ResearchCampaignsLaunchRequest
  - `campaignName` string, required
  - `description` string: The study's description, shown under its name on the results; display only, never asked of respondents.
  - `businessProfileId` string, uuid, required: The business profile whose customers the study interviews.
  - `targetKind` 'profile' | 'physical_locations': The profile's own customers (default), or every customer generated for its current store overlays.
  - `targetedGroupIds` string[], nullable, required: Saved audiences to interview, or null for the whole cohort.
  - `targetedCustomerIds` string[], nullable, required: Explicit customers to interview, or null. Never together with saved audiences.
  - `targetInterviewCount` integer, required
  - `researchFocus` string, required: The study's research focus, screened whole by acceptable use: at most 2,000 characters.
  - `schedule` 'once' | 'weekly' | 'monthly', required
  - `questions` ResearchQuestionsItem[]: The whole edited instrument; absent, the study asks its own questions. 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
  - `kind` 'backtest': backtest when the study re-asks a decision the business already made: its situation is the shared material every twin reads first, and its results compare with the outcome recorded on its Overview. Omit it for any other study.
  - `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.
  - `backtest` object: For a backtest only: its decision mapping (the single-choice question that asks the decision and what each option keeps) and the real-world outcome, recorded at launch. No model ever reads the outcome. Both stay editable on its Overview.
    - `decision` object
      - `questionId` string, required: The single-choice question that asks the decision.
      - `keeps` number[], required: By option position: the share of usual buying the answer keeps (0 stops, 1 keeps, up to 2 buys more), or null to leave it out.
    - `outcome` object
      - `metric` string, required: What was measured, such as "Units sold a week".
      - `change` number, required: The measured change, as a fraction: -0.3 is a 30% drop.
      - `note` string, nullable

## Response `202`

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

- ResearchCampaignsLaunchResponse
  - `runId` string, uuid, required: The billing run of the campaign's first interviews.
  - `entryId` string, required: The campaign entry this request started; read its progress with campaigns.campaign-entries.get.v1.
  - `status` 'workflow_started' | 'encounter_coordination_required', required: How the first run starts.
  - `campaignId` string, uuid, required
  - `study` 'ad_copy' | 'brand_health' | 'offers' | 'pricing' | 'product' | 'product_launch' | 'sales' | 'custom' | 'product_roadmap', required

## 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)