Outcomes#

Read what moved: results by channel, daily site analytics and success events, what customers said when asked how they heard about you, and promo codes and tagged links. Also record outcomes your team reports for a campaign, kept apart from observed evidence.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/outcomes/definitions#

List reusable reported outcome definitions for a workspace.

bash

GET /v1/outcomes/definitions?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

POST /v1/outcomes/definitions#

Create a reusable definition for a reported business or brand outcome such as sales value, awareness, or qualified inquiries, with a name, value kind, unit label, and default currency.

bash

POST /v1/outcomes/definitions
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "name": "My Campaign",
  "value_kind": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
name	`string`	Required	Short name of the outcome, for example "Sales value" or "Qualified inquiries".
description	`string \| null`	—	What the outcome measures and how it is normally sourced.
valueKind	`'count' \| 'currency' \| 'percentage' \| 'ratio' \| 'index' \| 'duration' \| 'other'`	Required	What kind of quantity measurements carry: count, currency, percentage, ratio, index, duration, or other.
unitLabel	`string \| null`	—	Unit shown after values, for example "inquiries" or "points".
defaultCurrency	`string \| null`	—	ISO 4217 currency code applied to currency-kind measurements, for example "NZD".

Response#

Returns { data, _meta } with the result.

PATCH /v1/outcomes/definitions/:id#

Update the name, description, value kind, unit label, or default currency of a reusable reported outcome definition.

bash

PATCH /v1/outcomes/definitions/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
name	`string`	—	Short name of the outcome, for example "Sales value" or "Qualified inquiries".
description	`string \| null`	—	What the outcome measures and how it is normally sourced.
valueKind	`'count' \| 'currency' \| 'percentage' \| 'ratio' \| 'index' \| 'duration' \| 'other'`	—	What kind of quantity measurements carry: count, currency, percentage, ratio, index, duration, or other.
unitLabel	`string \| null`	—	Unit shown after values, for example "inquiries" or "points".
defaultCurrency	`string \| null`	—	ISO 4217 currency code applied to currency-kind measurements, for example "NZD".
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.

DELETE /v1/outcomes/definitions/:id#

Delete an unused reported outcome definition by soft deletion; definitions with active measurements are blocked.

bash

DELETE /v1/outcomes/definitions/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.

GET /v1/outcomes/measurements#

List reported outcome measurements for a campaign, including method, period, confidence, units, and definition.

bash

GET /v1/outcomes/measurements?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

POST /v1/outcomes/measurements#

Record a campaign-reported outcome measurement: the value, optional baseline value, reporting period start and end, market, source method, and confidence, stored as an append-only evidence claim.

bash

POST /v1/outcomes/measurements
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "campaign_id": "3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03",
  "outcome_definition_id": "...",
  "value": "...",
  "source_method": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Unique identifier (UUID v4).
outcomeDefinitionId	`string (UUID)`	Required	The reusable outcome definition this measures.
periodStart	`string \| null`	—	First day (YYYY-MM-DD) of the period the reported value covers.
periodEnd	`string \| null`	—	Last day (YYYY-MM-DD) of the period; must be on or after periodStart.
value	`number`	Required	The reported outcome value, in the definition's value kind and unit.
baselineValue	`unknown`	—	Comparable value before the campaign, when the report supplied one.
market	`string \| null`	—	Market or region the value applies to, for example "New Zealand".
sourceMethod	`'document_reported' \| 'manual' \| 'csv' \| 'api'`	Required	How the value was obtained: document_reported, manual entry, csv import, or api. Reported outcomes are claims, not observed attribution.
confidence	`number \| null`	—	Reporter's confidence in the value from 0 (none) to 1 (certain).

Response#

Returns { data, _meta } with the result.

PATCH /v1/outcomes/measurements/:id#

Update the value, baseline, period start and end, market, source method, or confidence of a reported outcome measurement, superseding its prior evidence claim when the value changes.

bash

PATCH /v1/outcomes/measurements/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
outcomeDefinitionId	`string (UUID)`	—	The reusable outcome definition this measures.
periodStart	`string \| null`	—	First day (YYYY-MM-DD) of the period the reported value covers.
periodEnd	`string \| null`	—	Last day (YYYY-MM-DD) of the period; must be on or after periodStart.
value	`number`	—	The reported outcome value, in the definition's value kind and unit.
baselineValue	`unknown`	—	Comparable value before the campaign, when the report supplied one.
market	`string \| null`	—	Market or region the value applies to, for example "New Zealand".
sourceMethod	`'document_reported' \| 'manual' \| 'csv' \| 'api'`	—	How the value was obtained: document_reported, manual entry, csv import, or api. Reported outcomes are claims, not observed attribution.
confidence	`number \| null`	—	Reporter's confidence in the value from 0 (none) to 1 (certain).
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.

DELETE /v1/outcomes/measurements/:id#

Delete a reported campaign outcome measurement by soft deletion.

bash

DELETE /v1/outcomes/measurements/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.

GET /v1/outcomes/analytics-history#

Fetch daily Google Analytics site metrics (sessions, users, page views) and success-metric event counts for a date range, zero-filled for days without data.

bash

GET /v1/outcomes/analytics-history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/outcomes/hdyhau#

Retrieve a summary of GA4 How Did You Hear About Us (HDYHAU) custom-dimension values for a date range, including raw responses, normalized source categories, response coverage, creator-marketing relevance, data-quality flags, and a daily evidence timeline. This does not assign conversions to creators or campaigns.

bash

GET /v1/outcomes/hdyhau?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.

PUT /v1/outcomes/hdyhau/mapping#

Create or update a reusable workspace-specific mapping that normalizes one raw GA4 HDYHAU response value for a dimension API name into a source label and category for future reporting. This changes classification only and does not assign attribution.

bash

PUT /v1/outcomes/hdyhau/mapping
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "dimension_api_name": "...",
  "raw_value": "...",
  "normalized_value": "...",
  "category": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
dimensionApiName	`string`	Required
rawValue	`string`	Required
normalizedValue	`string`	Required
category	`'creator' \| 'organic_social' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'podcast' \| 'search' \| 'referral' \| 'paid' \| 'events' \| 'other' \| 'unknown'`	Required	Normalized HDYHAU source category.

Response#

Returns { data, _meta } with the result.

GET /v1/outcomes/direct-signals#

Retrieve directly observed GA4 promo-code and manually tagged UTM-link evidence for a date range, including sessions, daily users, selected success outcomes, explicit creator/campaign/activity mappings, general referral-channel buckets (e.g. Facebook, Google organic, an AI assistant) with a per-bucket traffic summary, and zero-filled timeline data. This reports observed evidence and does not infer attribution.

bash

GET /v1/outcomes/direct-signals?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.

PUT /v1/outcomes/direct-signals/:signalId/mapping#

Update one discovered GA4 promo code or manually tagged UTM link by mapping it to exactly one Brandwave creator, campaign, or activity, grouping it under one general referral-channel bucket (e.g. Facebook, Google organic, an AI assistant) when it cannot be tied to a specific entity, or removing its existing mapping. The association is mutually exclusive, applies to all observed sessions, users, and outcomes for that signal, and does not infer causal attribution.

bash

PUT /v1/outcomes/direct-signals/:signalId/mapping
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "association": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
signalId	`string (UUID)`	Required	Discovered GA4 direct-signal identifier.
association	`unknown \| null`	Required	Exactly one association - a Brandwave creator, campaign, or activity, or a general referral-channel bucket - or null to remove the mapping.

Response#

Returns { data, _meta } with the result.

PUT /v1/outcomes/direct-signals/:signalId/ignored#

Ignore one discovered GA4 promo code or manually tagged UTM link as noise, or restore a previously ignored one. Ignored signals are hidden from the default reporting view and excluded from its headline counts, but retain their observed sessions, users, and outcomes and can be restored at any time. This changes triage state only and does not infer attribution.

bash

PUT /v1/outcomes/direct-signals/:signalId/ignored
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "ignored": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
signalId	`string (UUID)`	Required	Discovered GA4 direct-signal identifier.
ignored	`boolean`	Required	True to ignore the signal as noise, false to restore it for review.

Response#

Returns { data, _meta } with the result.

GET /v1/outcomes/channels#

Retrieve evidence by channel for a date range: each channel type with spend (social media, broadcast, out of home, print, events, podcasts, PR articles) walked across the evidence chain with spend and activity count, impressions, sessions from linked promo codes and tagged links, linked success events, and customer-reported HDYHAU mentions, plus a corroboration count of how many of the four steps hold direct evidence. Cells are null when the source that could see them is not connected. Nothing is inferred or attributed.

bash

GET /v1/outcomes/channels?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.