Reported outcomes#

Manage campaign-reported business and brand measurements without presenting them as observed attribution.

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.