API reference

Every endpoint of the OpenAPI document: auth, parameters, request fields, example request and responses.

On this page

Conventions
Endpoints
Identity
GET /whoami
GET /orgs
POST /orgs
GET /openapi.json
Campaigns
POST /campaigns
POST /campaigns/{id}/respondents
POST /campaigns/{id}/launch
GET /campaigns/{id}
GET /campaigns/{id}/results
Sessions
POST /launch
Exports
POST /campaigns/{id}/exports
GET /exports/{id}
GET /downloads/{token}/{filename}
Webhook events
GET /webhooks
POST /webhooks
GET /webhooks/{id}
PATCH /webhooks/{id}
DELETE /webhooks/{id}
POST /webhooks/{id}/simulate
GET /webhooks/{id}/deliveries
POST feedback.received
POST feedback.analyzed
Apps
GET /campaigns/{id}/installs
GET /devices
POST /apps/register
POST /apps/heartbeat
GET /campaigns/{campaignId}/app-installs
Launch
GET /public/pulse/{code}/access
POST /public/pulse/{code}/start
GET /campaigns/{campaignId}/launch-keys
POST /campaigns/{campaignId}/launch-keys
DELETE /campaigns/{campaignId}/launch-keys/{keyId}
PUT /campaigns/{campaignId}/launch-access

The machine-readable contract is the OpenAPI document: /api/v1/channel/openapi.json. It is the source of truth; this page is the readable form. Base URL: https://api.wtn.live. Every response is JSON; every refusal uses the error envelope.

Conventions

Authenticate server calls with Authorization: Bearer wtn_<prefix>_<secret> (or X-API-Key). App calls need no secret: the campaign code is public.
A key that reaches several workspaces sends X-WTN-Workspace.
Send Idempotency-Key on a POST to make a retry safe for 24 hours. launch and webhooks do not take it, because their responses are secrets.
Lists are cursor-paged: ?limit=&cursor= returns { items, nextCursor }; pass nextCursor back until it is null.
Changes are additive. Read CSV columns by header, not position.

Endpoints

Generated from the OpenAPI document, grouped by area. Deprecated operations are listed last in their area.

Authentication schemes

Field	Description
`bearerApiKey`HTTP bearer, wtn_<prefix>_<secret>	Send your API key as `Authorization: Bearer wtn_…`. `X-API-Key: wtn_…` is accepted identically.
`studioJwt`HTTP bearer, JWT	A signed-in Studio/Admin session token. Used only by the launch-key and install-list routes that a person manages from Studio; the permission each needs is named on the route.

Identity

GET`/whoami`

The calling key's own identity — the first call any integration makes.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/whoami" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Example response · 200

{
  "serviceAccountId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "accountId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "scopes": [
    "scopes"
  ],
  "keyPrefix": "keyPrefix",
  "workspaceAllowlist": [
    "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
  ],
  "defaultWorkspaceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "orgId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
}

Responses

Status	Meaning
`200`	OK
`401`	No key, or the key is invalid/revoked/expired.

GET`/orgs`

Which workspaces this key may act on.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/orgs" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Example response · 200

{
  "workspaces": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "name": "name",
      "slug": "slug",
      "status": "status",
      "externalRef": "externalRef",
      "createdAt": "2026-10-20T09:30:00Z"
    }
  ],
  "total": 1,
  "defaultWorkspaceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
}

Responses

Status	Meaning
`200`	OK
`403`	The key has no business (NO_ORG).
`429`	Hourly workspaces quota exhausted.

POST`/orgs`

Create the workspace for one of your own clients, idempotent on your externalRef (scope channel:workspaces).

The workspace joins your business and starts PENDING_APPROVAL — a WTN reviewer approves it before a campaign can launch. The creating key may name it in X-WTN-Workspace straight away; other keys are not widened. Replaying the same ref with the same details answers 200 with the same workspace; the same ref with different details is refused 409.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`Idempotency-Key`header · string · optional	An opaque string that makes this POST replay-safe for 24 hours. The same key with a different body is refused (CONFLICT); the same key with the same body replays the original response.

Request body

Field	Description
`externalRef`string · required	Your own stable id for this client. The same ref always means the same workspace.
`name`string · required
`type`enum · optional	One of: INDIVIDUAL, COMPANY, PARTNERSHIP, GOVERNMENT, EDUCATIONAL, OTHER. Default: "COMPANY".
`team`string · optional
`location`string · optional

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/orgs" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalRef": "externalRef",
  "name": "name",
  "type": "COMPANY",
  "team": "team",
  "location": "location"
}'

Example response · 200

{
  "workspace": {
    "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "name": "name",
    "slug": "slug",
    "status": "status",
    "externalRef": "externalRef",
    "createdAt": "2026-10-20T09:30:00Z"
  },
  "created": true
}

Example response · 201

{
  "workspace": {
    "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "name": "name",
    "slug": "slug",
    "status": "status",
    "externalRef": "externalRef",
    "createdAt": "2026-10-20T09:30:00Z"
  },
  "created": true
}

Responses

Status	Meaning
`200`	The ref already named this workspace with the same details (a replay).
`201`	Created.
`400`	Validation failed.
`403`	The key lacks `channel:workspaces`, or has no business (NO_ORG).
`409`	The ref exists with different details, or an Idempotency-Key conflict.
`429`	Hourly workspace-creation quota, or the business workspace limit, exhausted.

GET`/openapi.json`

This document. No authentication required.

Authentication: none (public)

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/openapi.json"

Responses

Status	Meaning
`200`	OK

Campaigns

POST`/campaigns`

Provision a campaign — generate or reuse a survey, publish it, create the campaign.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.
`Idempotency-Key`header · string · optional	An opaque string that makes this POST replay-safe for 24 hours. The same key with a different body is refused (CONFLICT); the same key with the same body replays the original response.

Request body

Field	Description
`brief`object · optional
`brief.intentText`string · optional
`brief.constraints`object · optional
`brief.constraints.questionCount`integer · optional
`brief.constraints.languages`array of string · optional
`brief.constraints.tone`string · optional
`brief.constraints.bannedTopics`array of string · optional
`surveyId`string (uuid) · optional
`name`string · optional
`quality`object · optional
`quality.targetCount`integer · optional
`quality.maxResponses`integer · optional
`quality.minDurationSecs`integer · optional
`quality.minCoverageRatio`number · optional
`quality.minAnswerWords`integer · optional
`delivery`object · optional
`delivery.channels`array of enum · optional
`delivery.reminderCount`integer · optional
`delivery.audioRetentionDays`integer · optional
`delivery.greetByName`boolean · optional
`order`object · optional
`order.packageType`string · optional
`order.quotedPriceInr`integer · optional
`order.acceptedResponsesCommitted`integer · optional

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/campaigns" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "brief": {
    "intentText": "intentText",
    "constraints": {
      "questionCount": 1,
      "languages": [
        "languages"
      ],
      "tone": "tone",
      "bannedTopics": [
        "bannedTopics"
      ]
    }
  },
  "surveyId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "name": "name",
  "quality": {
    "targetCount": 1,
    "maxResponses": 1,
    "minDurationSecs": 1,
    "minCoverageRatio": 1,
    "minAnswerWords": 1
  },
  "delivery": {
    "channels": [
      "EMAIL"
    ],
    "reminderCount": 1,
    "audioRetentionDays": 1,
    "greetByName": true
  },
  "order": {
    "packageType": "packageType",
    "quotedPriceInr": 1,
    "acceptedResponsesCommitted": 1
  }
}'

Responses

Status	Meaning
`201`	Created
`400`	Validation failed, or neither/both of `brief`/`surveyId` were sent.
`404`	Unknown or foreign workspace.
`409`	Idempotency-Key conflict (different body, or a request already in flight).
`429`	Hourly provision quota exhausted.

POST`/campaigns/{id}/respondents`

Attach an audience by your own externalRef; get invitation links back.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.
`Idempotency-Key`header · string · optional	An opaque string that makes this POST replay-safe for 24 hours. The same key with a different body is refused (CONFLICT); the same key with the same body replays the original response.

Request body

Field	Description
`rows`array of object · required
`rows[].externalRef`string · required
`rows[].name`string · optional
`rows[].email`string (email) · optional
`rows[].phone`string · optional

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/campaigns/{id}/respondents" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "externalRef": "externalRef",
      "name": "name",
      "email": "name@example.com",
      "phone": "phone"
    }
  ]
}'

Responses

Status	Meaning
`200`	OK — one outcome per input row.
`400`	Validation failed, or too many rows.
`404`	Unknown campaign, or a foreign workspace.
`429`	Hourly audience quota exhausted.

POST`/campaigns/{id}/launch`

Go live. Refusals name the exact readiness blocker.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.
`Idempotency-Key`header · string · optional	An opaque string that makes this POST replay-safe for 24 hours. The same key with a different body is refused (CONFLICT); the same key with the same body replays the original response.

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/campaigns/{id}/launch" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`200`	OK
`400`	Not launch-ready — the description names the blocker.
`404`	Unknown campaign, or a foreign workspace.

GET`/campaigns/{id}`

Status, readiness and counts.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/campaigns/{id}" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`200`	OK
`404`	Unknown campaign, or a foreign workspace.

GET`/campaigns/{id}/results`

The per-campaign aggregate results projection. Never per-person.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/campaigns/{id}/results" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`200`	OK
`404`	Unknown campaign, or a foreign workspace.

Sessions

POST`/launch`

Mint a one-time link for one respondent session, carrying your own context (scope sessions:launch).

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Request body

Field	Description
`campaignId`string (uuid) · required
`externalUserRef`string · optional	Your own id for the person. Stored only as a keyed hash, never raw.
`language`string · optional	The session language (a language code such as `en`, `ar`). It rides on the link as `?lang=`; a language the campaign does not offer falls back to the campaign default, never an error.
`device`object · optional	Short labels (at most 64 characters each).
`device.platform`string · optional
`device.osName`string · optional
`device.osVersion`string · optional
`device.deviceVendor`string · optional
`device.deviceModel`string · optional
`device.browserName`string · optional
`device.browserVersion`string · optional
`device.appId`string · optional
`device.appVersion`string · optional
`device.appBuild`string · optional
`device.sdkVersion`string · optional
`device.locale`string · optional
`device.timezone`string · optional
`device.networkType`string · optional
`attributes`object · optional	At most 64 keys and 8 KB of JSON; values are strings, numbers or booleans only.

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/launch" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "externalUserRef": "externalUserRef",
  "language": "language",
  "device": {
    "platform": "platform",
    "osName": "osName",
    "osVersion": "osVersion",
    "deviceVendor": "deviceVendor",
    "deviceModel": "deviceModel",
    "browserName": "browserName",
    "browserVersion": "browserVersion",
    "appId": "appId",
    "appVersion": "appVersion",
    "appBuild": "appBuild",
    "sdkVersion": "sdkVersion",
    "locale": "locale",
    "timezone": "timezone",
    "networkType": "networkType"
  },
  "attributes": {}
}'

Example response · 201

{
  "url": "url",
  "expiresAt": "2026-10-20T09:30:00Z"
}

Responses

Status	Meaning
`201`	Created. The link works once and expires in about 10 minutes.
`400`	Oversized or malformed context: attributes over 64 keys or 8 KB, non-primitive values.
`403`	The key lacks the `sessions:launch` scope.
`404`	Unknown campaign, or one in another workspace.
`409`	The campaign is not collecting yet.
`429`	Hourly launch quota exhausted.

Exports

POST`/campaigns/{id}/exports`

Request the campaign’s open-tier export as JSON or PDF (scope channel:export; verbatim answers also need channel:transcripts, JSON only).

The file is the documented open schema wtn.partner-export.v1: study honesty block, funnel, per-question scores, themes and narrative. WTN-exclusive components (signature visualisations, cross-attribution, the composite integrity/attrition index) are NOT included; the document lists them under exclusions. No raw respondent PII, ever.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.
`Idempotency-Key`header · string · optional	An opaque string that makes this POST replay-safe for 24 hours. The same key with a different body is refused (CONFLICT); the same key with the same body replays the original response.

Request body

Field	Description
`format`enum · required	One of: json, pdf.
`includeTranscripts`boolean · optional	JSON only; needs `channel:transcripts`.

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/campaigns/{id}/exports" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "format": "json",
  "includeTranscripts": true
}'

Responses

Status	Meaning
`202`	Queued. Poll `GET /exports/{id}` for the signed download link.
`400`	Validation failed, or transcripts were requested for a PDF.
`403`	The key lacks `channel:export` (or `channel:transcripts` for transcripts).
`404`	Unknown campaign, or a foreign workspace.
`429`	Hourly export quota exhausted.
`503`	The export worker or the PDF renderer is not available.

GET`/exports/{id}`

An export’s status; READY carries a fresh signed download link (scope channel:export).

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/exports/{id}" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`200`	OK. Status is QUEUED, RUNNING, READY, FAILED or EXPIRED.
`404`	Unknown export, or another workspace’s.

GET`/downloads/{token}/{filename}`

Download an export file. No key: the signed link is the capability, and it expires.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`token`path · string · required
`filename`path · string · required

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/downloads/{token}/{filename}" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`200`	The file (`application/json` or `application/pdf`).
`404`	The link is expired, tampered with, or its key was revoked (one answer for all).
`429`	This link was fetched too often this hour.

Webhook events

GET`/webhooks`

This workspace's webhook subscriptions. Never includes the signing secret.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/webhooks" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Example response · 200

{
  "subscription": {
    "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "url": "https://example.com/path",
    "description": "description",
    "eventTypes": [
      "eventTypes"
    ],
    "isActive": true,
    "disabledAt": "2026-10-20T09:30:00Z",
    "disabledReason": "disabledReason",
    "createdAt": "2026-10-20T09:30:00Z"
  },
  "secret": "secret"
}

Responses

Status	Meaning
`200`	OK

POST`/webhooks`

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Request body

Field	Description
`url`string (uri) · required	https:// only; must resolve to a public address.
`description`string · optional
`eventTypes`array of string · optional	Empty or omitted = every event for this workspace. Events: `respondent.acknowledged`, `feedback.received`, `feedback.analyzed` (payloads under `webhooks` in this document).

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/webhooks" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/path",
  "description": "description",
  "eventTypes": [
    "eventTypes"
  ]
}'

Example response · 201

{
  "subscription": {
    "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "url": "https://example.com/path",
    "description": "description",
    "eventTypes": [
      "eventTypes"
    ],
    "isActive": true,
    "disabledAt": "2026-10-20T09:30:00Z",
    "disabledReason": "disabledReason",
    "createdAt": "2026-10-20T09:30:00Z"
  },
  "secret": "secret"
}

Responses

Status	Meaning
`201`	Created
`400`	The URL failed the SSRF check, or an unknown event type was named.

GET`/webhooks/{id}`

One subscription.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/webhooks/{id}" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`200`	OK
`404`	Unknown subscription.

PATCH`/webhooks/{id}`

Update the URL, description, event filter, or active state.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Request body

Field	Description
`url`string (uri) · optional
`description`string \| null · optional
`eventTypes`array of string · optional
`isActive`boolean · optional

Example request

curl -X PATCH "https://api.wtn.live/api/v1/channel/webhooks/{id}" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/path",
  "description": "description",
  "eventTypes": [
    "eventTypes"
  ],
  "isActive": true
}'

Responses

Status	Meaning
`200`	OK
`404`	Unknown subscription.

DELETE`/webhooks/{id}`

Remove a subscription. Its delivery trail is deleted with it.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Example request

curl -X DELETE "https://api.wtn.live/api/v1/channel/webhooks/{id}" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`204`	Deleted
`404`	Unknown subscription.

POST`/webhooks/{id}/simulate`

Send a synthetic webhook.test delivery — prove your endpoint and signature check before a real campaign depends on them.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.

Example request

curl -X POST "https://api.wtn.live/api/v1/channel/webhooks/{id}/simulate" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Example response · 201

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "eventId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "eventType": "eventType",
  "status": "PENDING",
  "attempts": 1,
  "nextAttemptAt": "2026-10-20T09:30:00Z",
  "lastStatusCode": 1,
  "lastError": "lastError",
  "occurredAt": "2026-10-20T09:30:00Z",
  "deliveredAt": "2026-10-20T09:30:00Z"
}

Responses

Status	Meaning
`201`	Queued
`404`	Unknown subscription.

GET`/webhooks/{id}/deliveries`

This subscription's delivery trail — keyset-paged.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.
`limit`query · integer · optional
`cursor`query · string (uuid) · optional

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Responses

Status	Meaning
`200`	OK
`404`	Unknown subscription.

EVENT`feedback.received`

A respondent finished a feedback session. Signed like every webhook (see the webhook guide).

Request body

Field	Description
`conversationId`string (uuid) · optional
`campaignId`string (uuid) · optional
`publicRef`string · optional
`appInstallId`string \| null (uuid) · optional
`answered`integer · optional
`total`integer · optional

Responses

Status	Meaning
`2XX`	Acknowledge with any 2xx; anything else is retried with backoff.

EVENT`feedback.analyzed`

The analysis of a finished session completed (once per session).

Request body

Field	Description
`conversationId`string (uuid) · optional
`campaignId`string (uuid) · optional
`publicRef`string \| null · optional
`appInstallId`string \| null (uuid) · optional
`answers`integer · optional
`exchanges`integer · optional
`analyzersRun`integer · optional
`analyzersReused`integer · optional

Responses

Status	Meaning
`2XX`	Acknowledge with any 2xx; anything else is retried with backoff.

Apps

GET`/campaigns/{id}/installs`

App installs registered against a campaign, cursor-paged (scope channel:results).

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`id`path · string (uuid) · required
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.
`limit`query · integer · optional	Default: 50.
`cursor`query · string · optional

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/campaigns/{id}/installs" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Example response · 200

{
  "items": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "campaignId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "appId": "appId",
      "platform": "ios",
      "appVersion": "appVersion",
      "deviceModel": "deviceModel",
      "osVersion": "osVersion",
      "locale": "locale",
      "status": "ACTIVE",
      "firstSeenAt": "2026-10-20T09:30:00Z",
      "lastSeenAt": "2026-10-20T09:30:00Z",
      "heartbeatCount": 1,
      "sessionCount": 1,
      "deviceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "userId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "identity": "anonymous",
      "hasEmail": true,
      "hasPhone": true,
      "feedbackCount": 1,
      "recentSessions": [
        "2026-10-20T09:30:00Z"
      ],
      "appSessionCount": 1
    }
  ],
  "nextCursor": "nextCursor"
}

Responses

Status	Meaning
`200`	OK
`400`	A tampered or unreadable cursor.
`404`	Unknown campaign, or one in another workspace.

GET`/devices`

The workspace's app devices (identity v2), cursor-paged (scope channel:results). No email or phone.

Authentication: bearerApiKey (HTTP bearer, wtn_<prefix>_<secret>)

Parameters

Field	Description
`X-WTN-Workspace`header · string (uuid) · optional	Which workspace this call acts on. Optional only when the key can reach exactly one workspace (see GET /whoami). Required, and refused with WORKSPACE_REQUIRED, when it can reach more than one.
`limit`query · integer · optional	Default: 50.
`cursor`query · string · optional
`appId`query · string · optional

Example request

curl -X GET "https://api.wtn.live/api/v1/channel/devices" \
  -H "Authorization: Bearer $WTN_BEARER_API_KEY"

Example response · 200

{
  "items": [
    {
      "deviceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "userId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "identity": "anonymous",
      "hasEmail": true,
      "hasPhone": true,
      "appId": "appId",
      "platform": "ios",
      "appVersion": "appVersion",
      "deviceModel": "deviceModel",
      "osVersion": "osVersion",
      "locale": "locale",
      "metadata": {},
      "status": "ACTIVE",
      "firstSeenAt": "2026-10-20T09:30:00Z",
      "lastSeenAt": "2026-10-20T09:30:00Z",
      "heartbeatCount": 1,
      "feedbackCount": 1,
      "sessionCount": 1,
      "recentSessions": [
        "2026-10-20T09:30:00Z"
      ]
    }
  ],
  "nextCursor": "nextCursor"
}

Responses

Status	Meaning
`200`	OK
`400`	A tampered or unreadable cursor.

POST`/apps/register`

An app registers itself against a campaign public code and gets a signed install id (no account, no secret).

Authentication: none (public)

Parameters

Field	Description
`Idempotency-Key`header · string · optional	An opaque string that makes this POST replay-safe for 24 hours. The same key with a different body is refused (CONFLICT); the same key with the same body replays the original response.

Request body

Field	Description
`campaignCode`string · required	The campaign's public code (the `<code>` in `/p/<code>`).
`appId`string · required	Your bundle id / package name.
`platform`enum · required	One of: ios, android, web, other.
`appVersion`string · required
`deviceModel`string · optional
`osVersion`string · optional
`locale`string · optional	BCP-47 tag of the app UI language.
`language`string · optional	The session language; used when `locale` is not sent.
`deviceId`string (uuid) · optional	The `deviceId` this app was given before. Honoured ONLY together with `refreshToken`; an id alone is ignored.
`refreshToken`string · optional	The secret that proves the app owns `deviceId`.
`vendorDeviceId`string · optional	An id the app persists across re-installs (IDFV / ANDROID_ID): finds the same device again.
`user`object · optional	Who is using the app. Without it the device is `anonymous`.
`user.externalId`string · optional	Your own user id.
`user.email`string (email) · optional	Stored encrypted, never returned.
`user.phone`string · optional	E.164, e.g. `+919876543210`. Stored encrypted, never returned.
`user.userHash`string · optional	Hex HMAC-SHA256 of `externalId` keyed with an active launch-key secret of the campaign. Marks the user `verified`; a wrong one is `401 USER_HASH_INVALID`.
`metadata`object · optional	Flat string labels of your own, at most 32 keys and 2 KB.

Example request

curl -X POST "https://api.wtn.live/api/v1/apps/register" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignCode": "campaignCode",
  "appId": "appId",
  "platform": "ios",
  "appVersion": "appVersion",
  "deviceModel": "deviceModel",
  "osVersion": "osVersion",
  "locale": "locale",
  "language": "language",
  "deviceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "refreshToken": "refreshToken",
  "vendorDeviceId": "vendorDeviceId",
  "user": {
    "externalId": "externalId",
    "email": "name@example.com",
    "phone": "phone",
    "userHash": "userHash"
  },
  "metadata": {}
}'

Example response · 201

{
  "deviceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "userId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "identity": "anonymous",
  "accessToken": "accessToken",
  "accessTokenExpiresAt": "2026-10-20T09:30:00Z",
  "refreshToken": "refreshToken",
  "refreshTokenExpiresAt": "2026-10-20T09:30:00Z",
  "installId": "installId",
  "heartbeatIntervalSecs": 1,
  "expiresAt": "2026-10-20T09:30:00Z"
}

Responses

Status	Meaning
`200`	Replay of the same Idempotency-Key: the SAME install id (header `Idempotency-Replayed: true`).
`201`	Registered.
`400`	Validation failed.
`401`	`USER_HASH_INVALID`: the userHash did not verify, or a verified user was addressed without one.
`403`	`INSTALL_BLOCKED`: this device was blocked by the workspace.
`404`	Unknown campaign code.
`409`	The campaign is not collecting yet, or an Idempotency-Key conflict.
`429`	This network registered too many installs this hour.

POST`/apps/heartbeat`

An app says it is alive. v2 (deviceId + refreshToken) returns a fresh access token on every call and works with an expired one; v1 (installId) returns a fresh install id late in its life.

Authentication: none (public)

Request body

Field	Description
`deviceId`string (uuid) · optional
`refreshToken`string · optional
`installId`string · optional
`appVersion`string · optional
`osVersion`string · optional
`locale`string · optional

Example request

curl -X POST "https://api.wtn.live/api/v1/apps/heartbeat" \
  -H "Content-Type: application/json" \
  -d '{
  "deviceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "refreshToken": "refreshToken",
  "installId": "installId",
  "appVersion": "appVersion",
  "osVersion": "osVersion",
  "locale": "locale"
}'

Example response · 200

{
  "ok": true,
  "heartbeatIntervalSecs": 1,
  "accessToken": "accessToken",
  "accessTokenExpiresAt": "2026-10-20T09:30:00Z",
  "refreshTokenExpiresAt": "2026-10-20T09:30:00Z",
  "installId": "installId",
  "expiresAt": "2026-10-20T09:30:00Z"
}

Responses

Status	Meaning
`200`	OK
`401`	`INSTALL_INVALID` (v1: the install id is forged, expired, another campaign's, unknown or blocked) or `DEVICE_AUTH_INVALID` (v2: unknown device, wrong, expired or revoked refresh token — call register again).
`429`	This install or device heartbeats too often.

GET`/campaigns/{campaignId}/app-installs`

The same install list for a Studio session (campaign:view), cursor-paged.

Authentication: studioJwt (HTTP bearer, JWT)

Parameters

Field	Description
`campaignId`path · string (uuid) · required
`limit`query · integer · optional	Default: 50.
`cursor`query · string · optional

Example request

curl -X GET "https://api.wtn.live/api/v1/campaigns/{campaignId}/app-installs" \
  -H "Authorization: Bearer $WTN_STUDIO_JWT"

Example response · 200

{
  "items": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "campaignId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "appId": "appId",
      "platform": "ios",
      "appVersion": "appVersion",
      "deviceModel": "deviceModel",
      "osVersion": "osVersion",
      "locale": "locale",
      "status": "ACTIVE",
      "firstSeenAt": "2026-10-20T09:30:00Z",
      "lastSeenAt": "2026-10-20T09:30:00Z",
      "heartbeatCount": 1,
      "sessionCount": 1,
      "deviceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "userId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "identity": "anonymous",
      "hasEmail": true,
      "hasPhone": true,
      "feedbackCount": 1,
      "recentSessions": [
        "2026-10-20T09:30:00Z"
      ],
      "appSessionCount": 1
    }
  ],
  "nextCursor": "nextCursor"
}

Responses

Status	Meaning
`200`	OK
`404`	Unknown campaign.

Launch

GET`/public/pulse/{code}/access`

What the page should show for this visit (read-only: a valid signed token is NOT used up).

Authentication: none (public)

Parameters

Field	Description
`code`path · string · required
`lt`query · string · optional	The signed launch token from the link.

Example request

curl -X GET "https://api.wtn.live/api/v1/public/pulse/{code}/access"

Example response · 200

{
  "requireSigned": true,
  "state": "NOT_REQUIRED",
  "refusal": {
    "code": "LAUNCH_SIGNATURE_REQUIRED",
    "title": "title",
    "description": "description"
  },
  "language": "language"
}

Responses

Status	Meaning
`200`	OK
`404`	Unknown topic.
`429`	This network checked too many links this hour.

POST`/public/pulse/{code}/start`

Start a session on an Open Pulse campaign (the respondent page calls this; integration fields documented).

Authentication: none (public)

Parameters

Field	Description
`code`path · string · required

Request body

Field	Description
`consentGiven`boolean · optional	Required `true`: nothing is created without consent.
`language`string · optional
`installId`string · optional	The signed install id from `?inst=`.
`deviceToken`string · optional	The app device access token from the page fragment `#dt=`. A valid one attributes the feedback to its device and person; a bad or expired one is ignored (the feedback stays anonymous).
`launchToken`string · optional	The signed launch token from `?lt=` (JWT HS256, see `/campaigns/{campaignId}/launch-keys`). Verified and used up here; a campaign that requires signing refuses a start without a valid one (`LAUNCH_SIGNATURE_REQUIRED` / `LAUNCH_TOKEN_INVALID`, 403).
`client`object · optional	Short device/app labels; unreadable values are ignored.

Example request

curl -X POST "https://api.wtn.live/api/v1/public/pulse/{code}/start" \
  -H "Content-Type: application/json" \
  -d '{
  "consentGiven": true,
  "language": "language",
  "installId": "installId",
  "deviceToken": "deviceToken",
  "launchToken": "launchToken",
  "client": {}
}'

Responses

Status	Meaning
`200`	Nothing created: the campaign is not open, consent or a site is still needed.
`201`	A session was created.
`403`	`LAUNCH_SIGNATURE_REQUIRED` / `LAUNCH_TOKEN_INVALID` on a signed-only campaign, or a challenge is required.
`429`	Too many attempts, or responses are paused for this campaign.

GET`/campaigns/{campaignId}/launch-keys`

The campaign's launch keys (never the secret) and whether signing is required (Studio session, campaign:view).

Authentication: studioJwt (HTTP bearer, JWT)

Parameters

Field	Description
`campaignId`path · string (uuid) · required

Example request

curl -X GET "https://api.wtn.live/api/v1/campaigns/{campaignId}/launch-keys" \
  -H "Authorization: Bearer $WTN_STUDIO_JWT"

Example response · 200

{
  "items": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "slot": 1,
      "fingerprint": "fingerprint",
      "createdAt": "2026-10-20T09:30:00Z",
      "lastUsedAt": "2026-10-20T09:30:00Z",
      "secret": "secret",
      "kid": "kid"
    }
  ],
  "requireSigned": true
}

Responses

Status	Meaning
`200`	OK
`404`	Unknown campaign, or one in another workspace.

POST`/campaigns/{campaignId}/launch-keys`

Create the next launch key (Studio session, campaign:build). The secret is returned ONCE. Rotation = create, switch the app, revoke the old.

Authentication: studioJwt (HTTP bearer, JWT)

Parameters

Field	Description
`campaignId`path · string (uuid) · required
`Idempotency-Key`header · string · optional	An opaque string that makes this POST replay-safe for 24 hours. The same key with a different body is refused (CONFLICT); the same key with the same body replays the original response.

Example request

curl -X POST "https://api.wtn.live/api/v1/campaigns/{campaignId}/launch-keys" \
  -H "Authorization: Bearer $WTN_STUDIO_JWT"

Example response · 201

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "slot": 1,
  "fingerprint": "fingerprint",
  "createdAt": "2026-10-20T09:30:00Z",
  "lastUsedAt": "2026-10-20T09:30:00Z",
  "secret": "secret",
  "kid": "kid"
}

Responses

Status	Meaning
`200`	Replay of the same Idempotency-Key: the same key, `secret: null`.
`201`	Created, with the secret.
`403`	The session lacks `campaign:build`.
`404`	Unknown campaign, or one in another workspace.
`409`	Both key slots are in use: revoke one first.

DELETE`/campaigns/{campaignId}/launch-keys/{keyId}`

Revoke a launch key at once (Studio session, campaign:build).

Authentication: studioJwt (HTTP bearer, JWT)

Parameters

Field	Description
`campaignId`path · string (uuid) · required
`keyId`path · string (uuid) · required

Example request

curl -X DELETE "https://api.wtn.live/api/v1/campaigns/{campaignId}/launch-keys/{keyId}" \
  -H "Authorization: Bearer $WTN_STUDIO_JWT"

Responses

Status	Meaning
`204`	Revoked.
`404`	Unknown key.

PUT`/campaigns/{campaignId}/launch-access`

Require (or stop requiring) a signed launch for this campaign (Studio session, campaign:build).

Authentication: studioJwt (HTTP bearer, JWT)

Parameters

Field	Description
`campaignId`path · string (uuid) · required

Request body

Field	Description
`requireSigned`boolean · required

Example request

curl -X PUT "https://api.wtn.live/api/v1/campaigns/{campaignId}/launch-access" \
  -H "Authorization: Bearer $WTN_STUDIO_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "requireSigned": true
}'

Responses

Status	Meaning
`200`	The setting now in force.
`404`	Unknown campaign.

API reference

Conventions#

Endpoints#

Authentication schemes

Identity#

GET/whoami#

Responses

GET/orgs#

Responses

POST/orgs#

Parameters

Request body

Responses

GET/openapi.json#

Responses

Campaigns#

POST/campaigns#

Parameters

Request body

Responses

POST/campaigns/{id}/respondents#

Parameters

Request body

Responses

POST/campaigns/{id}/launch#

Parameters

Responses

GET/campaigns/{id}#

Parameters

Responses

GET/campaigns/{id}/results#

Parameters

Responses

Sessions#

POST/launch#

Parameters

Request body

Responses

Exports#

POST/campaigns/{id}/exports#

Parameters

Request body

Responses

GET/exports/{id}#

Parameters

Responses

GET/downloads/{token}/{filename}#

Parameters

Responses

Webhook events#

GET/webhooks#

Parameters

Responses

POST/webhooks#

Parameters

Request body

Responses

GET/webhooks/{id}#

Parameters

Responses

PATCH/webhooks/{id}#

Parameters

Request body

Responses

DELETE/webhooks/{id}#

Parameters

Responses

POST/webhooks/{id}/simulate#

Parameters

Responses

GET/webhooks/{id}/deliveries#

Parameters

Responses

EVENTfeedback.received#

Request body

Responses

EVENTfeedback.analyzed#

Request body

Responses

Apps#

Conventions

Endpoints

Identity

GET`/whoami`

GET`/orgs`

POST`/orgs`

GET`/openapi.json`

Campaigns

POST`/campaigns`

POST`/campaigns/{id}/respondents`

POST`/campaigns/{id}/launch`

GET`/campaigns/{id}`

GET`/campaigns/{id}/results`

Sessions

POST`/launch`

Exports

POST`/campaigns/{id}/exports`

GET`/exports/{id}`

GET`/downloads/{token}/{filename}`

Webhook events

GET`/webhooks`

POST`/webhooks`

GET`/webhooks/{id}`

PATCH`/webhooks/{id}`

DELETE`/webhooks/{id}`

POST`/webhooks/{id}/simulate`

GET`/webhooks/{id}/deliveries`

EVENT`feedback.received`

EVENT`feedback.analyzed`

Apps

GET`/campaigns/{id}/installs`

GET`/devices`

POST`/apps/register`

POST`/apps/heartbeat`

GET`/campaigns/{campaignId}/app-installs`

Launch

GET`/public/pulse/{code}/access`

POST`/public/pulse/{code}/start`

GET`/campaigns/{campaignId}/launch-keys`

POST`/campaigns/{campaignId}/launch-keys`

DELETE`/campaigns/{campaignId}/launch-keys/{keyId}`

PUT`/campaigns/{campaignId}/launch-access`