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
Authorization header. See the Authentication guide for setup instructions.GET /v1/outcomes/definitions
List reusable reported outcome definitions for a workspace.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.