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

NameTypeRequiredDescription
workspaceIdstring (UUID)RequiredWorkspace identifier.
provider'google' | 'meta'Required

Response

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

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. Until the workspace records advertising history, spend or budgets, an account in another currency is selectable and sets the workspace currency; after that, 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

NameTypeRequiredDescription
workspaceIdstring (UUID)RequiredWorkspace identifier.
provider'google' | 'meta'Required
discoveryIdstring (UUID)—Continue this workspace/provider discovery session.
offsetinteger—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. The first account in a workspace with no recorded advertising history, spend or budgets sets the workspace currency. 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

NameTypeRequiredDescription
workspaceIdstring (UUID)RequiredWorkspace identifier.
provider'google' | 'meta'Required
externalIdstringRequired
discoveryIdstring (UUID)RequiredDiscovery 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

NameTypeRequiredDescription
workspaceIdstring (UUID)RequiredWorkspace identifier.
accountIdstring (UUID)RequiredUnique 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

NameTypeRequiredDescription
workspaceIdstring (UUID)RequiredWorkspace identifier.
activityIdstring (UUID)RequiredUnique identifier (UUID v4).
startDatestringRequired
endDatestringRequired

Response

Returns { data, _meta } with the result.