--- title: "Launch campaigns" method: POST path: "/api/v1/discovery/campaigns/launch" tags: ["discovery"] deprecated: true --- # Launch campaigns `POST /api/v1/discovery/campaigns/launch` ## Request - Base URL: `https://point11.ai` - URL: `https://point11.ai/api/v1/discovery/campaigns/launch` - Auth: OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`) > **Deprecated.** Deprecated: use discovery.campaigns.launch.v2 (discovery_campaigns_launch_v2), which takes no replacesCampaignId: a campaign's settings change in place with discovery.campaign-settings.update.v2, so this version refuses a replacesCampaignId (PRECONDITION_FAILED, details.reason use_campaign_settings) and otherwise launches exactly as v2, naming the same campaign for the same Idempotency-Key. Start a Discovery campaign for a website or an existing business profile (url may be null when businessProfileId is supplied), for an organization whose Analytics subscription already admits work and whose payment method is on file. Its conversations accrue against the organization's Analytics plan as they run. This never subscribes, applies an offer, or asks for a card: an organization without an active subscription or saved payment method is refused and subscribes in the Point11 dashboard first. Returns the campaign; its setup runs in the background. ## Headers - `Point11-Organization` string, uuid - `Idempotency-Key` string, uuid, required ## Request body - DiscoveryCampaignsLaunchRequest - `form` DiscoveryForm, required: The campaign: name, website url (nullable when businessProfileId is supplied), mode (always current), business profile, saved audiences or explicit customers (the campaign runs exactly those; a targetCustomerCount, if sent, must equal their number), manual audiences, locations and their coverage, AI engines, margin of error, and optional customer target. - `name` string, required - `url` string, uri, nullable, required - `mode` 'current', required - `businessProfileId` string, uuid, nullable, required - `targetedGroupIds` string[], nullable, required - `targetedCustomerIds` string[], nullable, required - `manualAudiences` object[] - `id` string, required - `count` integer, required - `overrideManifest` union, required - DiscoveryOverrideManifest - `version` 3, required - `baseGenerationProfileId` string, required - `baseSourceHash` string, required - `profileName` string, required - `overrides` DiscoveryOverrides, required - `employerAccounts` object[] - `name` string, required - `domain` string, nullable, required - `givenFacts` DiscoveryGivenFacts - `age` object - … - `location` object - … - `household` union - … - `householdIncome` object - … - `jobTitle` string - `employer` string - `yearsInRole` object - … - `companySize` object - … - `annualRevenue` object - … - `stakeholders` string - `budget` string - `constraints` string - `situation` string - `trigger` string - `functionalNeed` string - `emotionalNeed` string - `socialNeed` string - `desiredOutcome` string - `labels` string[] - DiscoveryItemOverrideManifest - `version` 2, required - `baseGenerationProfileId` string, required - `baseSourceHash` string, required - `profileName` string, required - `overrides` DiscoveryOverrides, required - `employerAccounts` object[] - `name` string, required - `domain` string, nullable, required - object - `version` 1, required - `baseGenerationProfileId` string, required - `baseSourceHash` string, required - `profileName` string, required - `overrides` object, required - `locationContexts` DiscoveryLocationContextsItem[] - `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 - … - `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[] - `locationCoverageMode` 'standard' | 'one_per_location' - `engines` string[], required - `marginOfError` 10 | 5 | 1, required - `targetCustomerCount` integer: How many customers the campaign runs, in total across its locations; each has one conversation a month with every engine. Omit it for the sample marginOfError requires at 95% confidence, or 97 per location. At least 100 without locations, or one per location. A campaign of chosen customers (targetedCustomerIds) runs exactly those, so a count, if sent, is how many were chosen. - `expectedMonthlyPriceCents` integer: The Analytics monthly price the caller reviewed, in cents; a launch whose current price differs is refused (reason PRICE_CHANGED). - `replacesCampaignId` string, uuid: Refused: a campaign's settings change in place with discovery.campaign-settings.update.v2. Omit it to start a new campaign. ## Response `202` Accepted: the durable run started. Follow it with `GET /api/v1/platform/runs-v2/{id}`. - DiscoveryCampaignsLaunchResponse - `runId` string, nullable, required: The billing run the launch dispatched, or null: campaign setup is a background workflow, not a billing run, and bills its conversations as they are admitted. - `status` 'setup_started', required: `setup_started`: the campaign exists and its setup runs in the background (a retry of a launch already started answers the same). - `campaignId` string, uuid, required: The started campaign. Its first entry is admitted once its setup finishes, after this response; list its entries with campaigns.campaign-entries.list.v1. ## 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)