---
title: "Start campaigns (v4)"
method: POST
path: "/api/v1/experience/campaigns/start-v4"
tags: ["experience"]
---

# Start campaigns (v4)

`POST /api/v1/experience/campaigns/start-v4`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/experience/campaigns/start-v4`
- 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 an always-on Experience campaign over chosen customers (or, with follows, a share of a Discovery campaign's customers, as Bootup's Experience chooses them, which the campaign records and re-reads each run: a customer who left that campaign leaves, and a store its customers no longer cover lends its share, up to 100; while that campaign is archived its customers stay until it is restored, and once it is deleted, for good; or every customer at chosen stores, dealt one per store until 100, chosen once at launch: the business profile's stores by locationKeys, stores picked on Google Maps by locationContexts, or both) and pages (or one connected app version on one mobile device), on chosen devices, shopped by Point11's shopper or the agents named, each its vendor's model in Point11's browser, as its own visit. It shops its whole grid now; once accepted, a prorated share shops again over the rest of the UTC month, then every customer monthly, on the business's published hours; a first run with no delivered visit starts none. With competitorSourceCampaignId (a Discovery campaign on its profile), each run also shops every brand the customer's latest settled conversation there labelled a direct competitor, re-read each run, uncapped. Subscribes nothing: runs use the allowance (and pay-as-you-go, if on). Returns the campaign and its launch entry; runs dispatch soon. A Google Maps pick the profile has no customers at yet is set up first, as a Discovery campaign sets up a store (verified, researched as a store and given the customers a Discovery campaign samples at each store, a one-time customer-generation charge experience_campaigns_prescreen_v2 quotes): it then answers delivery setting_up_stores with the campaign id, and the campaign commits once the setup settles and shops its share of every store's customers, leaving out any store that could not be set up; the member who started it is emailed when a store was left out or the campaign could not start. A retry under the same Idempotency-Key answers what the setup became: still setting up, the campaign it committed, or, for a setup that ended without one, a conflict whose details.setupOutcome names how it ended; another body under that key is an idempotency conflict. iPhone Safari launches only with stores that already have customers. API keys name only stores that already have customers.

## Headers

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

## Request body

- ExperienceCampaignsStartV4Request
  - `campaignName` string, required
  - `browserDevices` string[]: The devices every customer shops each page on, each once; each device's visit is one experience run. Absent, desktop and mobile. A nativeApp names mobile alone.
  - `agents` string[]: The agents that shop every customer on every page and device, each once (1 to 5). point11 is Point11's own shopper; dots (OpenAI Dots), spark (Gemini Spark), muse (Meta Muse) and grok_bot (Grok Bot) each run the model that vendor's agent most likely uses, in Point11's browser, never as the real agent. Each agent's visit is one experience run at the same price. Absent, point11 alone. A settings Save changes them from the next cycle.
  - `businessProfileId` string, uuid, required
  - `customerIds` string[]: The customers who visit: at least one, and as many as the launch's 1,000 visits hold (each customer visits every page on every device with every agent). Not with follows or stores (locationKeys, locationContexts), which choose them.
  - `follows` ExperienceFollows: Instead of customerIds, follow a Discovery campaign for a share of its customers, as Bootup's Experience takes them: at the launch, of the customers on its roster the launch admits, in the order Discovery sampled them, the first 1 in sampleEvery (rounded up) at each of its stores, at most 100 dealt one per store. The campaign records the follow, and each later scheduled cycle re-reads that roster: a customer who left it leaves, each store the campaign's customers no longer cover lends its share up to 100, a customer still on it stays, and a Save changes no customers; while the followed campaign is archived the customers stay as they are and a restore resumes the follow at the next scheduled cycle, and once it is deleted they stay for good. A Forecast campaign lends its Forecast's customers. To shop each customer's direct competitors too, competitorSourceCampaignId names this same campaign.
    - `campaignId` string, uuid, required: A Discovery campaign on the same business profile (discovery_campaigns_list_v1's businessProfileId), active or paused, with a finished round.
    - `sampleEvery` integer, required: 1 in how many of its customers shop: 1 is every customer, at most 1 in 20.
  - `locationKeys` string[]: Instead of customerIds or follows, the business profile's stores whose customers visit (1 to 100): each a location key business_store_profile_summaries_get_v1 lists under businessProfileId; a key that is not one of its stores now is refused. At the launch, every customer at them the launch admits, dealt one per store in the profile's store order until 100, as a followed local Discovery campaign's share is at 1 in 1. They are chosen once and become the campaign's customers; nothing of the stores is recorded.
  - `destinationUrls` string[], required
  - `connectionAccess` object
    - `connection` object, required
      - `connectionId` string, uuid, required
      - `revision` integer, required
    - `account` object
      - `accountId` string, uuid, required
      - `revision` integer, required
  - `nativeApp` object
    - `platform` 'ios' | 'android', required
    - `buildId` string, uuid, required
    - `sha256` string, required
    - `appId` string, required
    - `versionLabel` string, required
    - `deviceName` string, required
    - `osVersion` string, required
  - `objective` string, required
  - `competitorSourceCampaignId` string, uuid: A Discovery campaign on the same business profile (discovery_campaigns_list_v1's businessProfileId). Each run, every customer also shops every brand its latest settled conversation there labelled a direct competitor; a customer with none shops the pages alone. Set at launch, never changed. Public websites only: not with connectionAccess or nativeApp.
  - `locationContexts` DiscoveryLocationContextsItem[]: Instead of customerIds or follows, and beside locationKeys, stores picked on Google Maps whose customers visit: each one store, one address (the finder's pick carries its googlePlace). A pick the business profile already has as a store with customers is that store; any other is set up first as a Discovery campaign sets up a store: verified on Google Maps, researched as a store and given 97 customers, a one-time customer-generation charge the prescreen quotes; the launch then shops its share of every store's customers. 100 stores at most with locationKeys. New stores that together would generate more than 5000 customers, the most one Discovery settings Save generates, refuse the launch (INVALID_INPUT), and so does a store Google Maps cannot place (LOCATION_UNMAPPABLE).
    - `addresses` DiscoveryAddressesItem[], required
      - `googlePlace` object, nullable
        - `placeId` string, required
        - `requestToken` string, uuid, required
        - `callId` string, uuid, required
        - `requestFingerprint` string, required
      - `label` string, nullable
      - `storeId` string, nullable
      - `street` string, nullable
      - `city` string, nullable
      - `region` string, nullable
      - `postalCode` string, nullable
      - `country` string, nullable
      - `latitude` number, nullable
      - `longitude` number, nullable
      - `url` string, nullable
      - `notes` string, nullable
      - `serviceArea` object
        - `campaignBoundary` object
          - `areas` object[], required
            - `query` string, required
            - `countryCode` string, nullable
            - `weightPct` number, nullable
          - `evidenceNote` string, nullable
        - `configuredRule` object
          - `strategy` 'premises_deepest_reliable', required
          - `version` 'physical-service-area:v1', required
    - `market` string, nullable
    - `country` string, nullable
    - `storeIds` string[]
    - `sourceNotes` string[]

## Response `200`

Success.

- ExperienceCampaignsStartV4Response
  - `campaignId` string, uuid, required: The campaign: committed when delivery is dispatching; while its stores are set up, the campaign the launch commits once they settle, absent from every campaign read until then, and named by this id for the same Idempotency-Key ever after.
  - `delivery` 'dispatching' | 'setting_up_stores', required: dispatching: the grid is committed and its units enter Billing's door after the response. setting_up_stores: stores the launch names have no customers yet; each is verified on Google Maps, researched and given its customers, then the campaign commits and shops, any store that could not be set up left out. The member who started it is emailed when a store was left out or the campaign could not start. Nothing is committed until then; a retry under the same Idempotency-Key answers what the setup became.
  - `campaignKey` string, nullable, required: The committed campaign's key; null while setting up stores.
  - `entryId` string, nullable, required: The campaign entry this request started; read its progress with campaigns.campaign-entries.get.v1.
  - `runUnitCount` integer, nullable, required: The units the grid committed; null while setting up stores.
  - `storeCount` integer, nullable, required: How many stores are being set up; null when dispatching.
  - `generatedCustomerCount` integer, nullable, required: How many customers their setup generates, 97 at each store as a Discovery campaign's store, a one-time customer-generation charge; null when dispatching.

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