Paid media#

Advertising accounts and provider-reported evidence beneath canonical Activities. Campaigns, creative context, dated spend, and platform-attributed results retain their provider provenance.

Authentication required

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

GET /v1/paid-media/accounts#

List selected advertising accounts for the Google or Meta provider, their currencies, synchronization progress, errors, and retained historical connection state for a workspace.

bash

GET /v1/paid-media/accounts?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&provider=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
provider	`'google' \| 'meta'`	Required

Response#

Returns { data, _meta } with the result.

GET /v1/paid-media/discover#

List advertiser accounts accessible through the connected Google or Meta provider grant using resumable discovery, including accounts beneath Google managers. Continue with discoveryId and offset through the stable result cache. Currency mismatches are shown but cannot be selected.

Owner only

bash

GET /v1/paid-media/discover?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&provider=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
provider	`'google' \| 'meta'`	Required
discoveryId	`string (UUID)`	—	Continue this workspace/provider discovery session.
offset	`integer`	—	Offset in the stable discovery result cache.

Response#

Returns { data, _meta } with the result.

POST /v1/paid-media/accounts/select#

Select a Google Ads or Meta Ads account by its external identifier and valid discoveryId for read-only synchronization. Multiple accounts can be selected under one provider grant. Immediately queues progressive historical import into Activities.

Owner only

bash

POST /v1/paid-media/accounts/select
Authorization: Bearer {token}
Content-Type: application/json

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
provider	`'google' \| 'meta'`	Required
externalId	`string`	Required
discoveryId	`string (UUID)`	Required	Discovery session that verified access to this advertiser.

Response#

Returns { data, _meta } with the result.

POST /v1/paid-media/accounts/remove#

Remove one advertising account from synchronization without deleting its historical Activities, spend, provider-reported performance, notes, files, or Brandwave Campaign links. Other selected accounts remain connected.

Owner only

bash

POST /v1/paid-media/accounts/remove
Authorization: Bearer {token}
Content-Type: application/json

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

Parameters#

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

Response#

Returns { data, _meta } with the result.

GET /v1/paid-media/performance#

Retrieve an imported Activity’s provider account, campaign, ad set or ad group, creative assets and text, destinations, and dated spend and delivery. Conversions and action values are provider-attributed evidence, not canonical business outcomes. Older Google observations may cover whole calendar months.

bash

GET /v1/paid-media/performance?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	Required	Unique identifier (UUID v4).
startDate	`string`	Required
endDate	`string`	Required

Response#

Returns { data, _meta } with the result.