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
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.
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 { 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.
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. 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.
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.
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.
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.