Activities#

Track delivered marketing activity across social, broadcast, out-of-home, print, events, podcasts, and PR.

Authentication required

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

GET /v1/activities#

Retrieve a paginated list of activities for an organization.

bash

GET /v1/activities?page_index=0&page_size=25&organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`string`	—	Column name to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.
channelType	`'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'`	—	Filter by channel group.
channelTypes	`Array<'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'>`	—	Filter by one or more channel groups.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'	—	Filter by specific channel.
channels	Array<'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'>	—	Filter by one or more specific channels.
creatorId	`string (UUID)`	—	Filter by creator identifier.
mediaProviderId	`string (UUID)`	—	Filter by media provider identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.
unlinkedFromCampaign	`boolean`	—	Exclude campaign-linked activities.
unlinkedFromCreatorId	`string (UUID)`	—	Exclude links to this creator.

Response#

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

GET /v1/activities/count#

Get the total number of activities matching the given filters.

bash

GET /v1/activities/count?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
channelType	`'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'`	—	Filter by channel group.
channelTypes	`Array<'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'>`	—	Filter by one or more channel groups.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'	—	Filter by specific channel.
channels	Array<'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'>	—	Filter by one or more specific channels.
creatorId	`string (UUID)`	—	Filter by creator identifier.
mediaProviderId	`string (UUID)`	—	Filter by media provider identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.

Response#

Returns { count, _meta }.

GET /v1/activities/stats#

Aggregate statistics for activities matching the given filters.

bash

GET /v1/activities/stats?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
channelType	`'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'`	—	Filter by channel group.
channelTypes	`Array<'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'>`	—	Filter by one or more channel groups.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'	—	Filter by specific channel.
channels	Array<'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'>	—	Filter by one or more specific channels.
creatorId	`string (UUID)`	—	Filter by creator identifier.
mediaProviderId	`string (UUID)`	—	Filter by media provider identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).

Response#

Returns { data, _meta } with the result.

POST /v1/activities#

Create social or provider-delivered activity with channel-specific delivery details, metrics, an optional creator or media provider, and an initial cost.

bash

POST /v1/activities
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "channel": "instagram",
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
channelType	`'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'`	—	Top-level channel group for this activity.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'	Required	Specific activity channel or subtype.
activity	`'instagram_story' \| 'instagram_post' \| 'instagram_reel' \| 'youtube_video' \| 'youtube_short' \| 'tiktok_video' \| 'twitter_post' \| 'linkedin_post' \| 'reddit_post' \| null`	—
name	`string`	Required	Activity name or title (max 500 characters).
startAt	`string (ISO 8601) \| null \| null`	—
endAt	`string (ISO 8601) \| null \| null`	—
creatorId	`string (UUID)`	—	Creator to auto-link to this activity.
mediaProviderId	`string (UUID) \| null`	—	Media provider for a provider-delivered activity.
impressions	`integer \| null`	—	Delivered or estimated impression count.
deliverySource	`'platform_reported' \| 'provider_reported' \| 'user_entered' \| 'benchmark_estimated' \| 'modeled' \| null`	—	Provenance of the delivered activity metrics.
deliverySourceMetadata	`object \| null`	—	Structured provenance metadata for delivered activity metrics.
initialCost	`object`	—	Optional initial cost line item to create with the activity.
broadcastDetails	`object`	—	Broadcast placement and delivery details.
outOfHomeDetails	`object`	—	Out-of-home placement and delivery details.
printDetails	`object`	—	Print placement and delivery details.
eventDetails	`object`	—	Event participation and delivery details.
podcastDetails	`object`	—	Podcast placement and delivery details.
prArticleDetails	`object`	—	PR article placement and delivery details.

Response#

Returns { data, _meta } with the result.

PATCH /v1/activities/:id#

Update an activity's channel, content link, metrics, media provider, or channel-specific delivery details.

bash

PATCH /v1/activities/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Activity identifier to update.
channelType	`'social_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles'`	—	Top-level channel group for this activity.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article'	—	Updated channel.
activity	`'instagram_story' \| 'instagram_post' \| 'instagram_reel' \| 'youtube_video' \| 'youtube_short' \| 'tiktok_video' \| 'twitter_post' \| 'linkedin_post' \| 'reddit_post' \| null`	—	Updated content type.
name	`string`	—	Updated activity name (max 500 characters).
startAt	`string (ISO 8601) \| null \| null`	—	Updated start date.
endAt	`string (ISO 8601) \| null \| null`	—	Updated end date.
mediaProviderId	`string (UUID) \| null`	—	Updated provider for a provider-delivered activity.
impressions	`integer \| null`	—	Updated delivered or estimated impression count.
deliverySource	`'platform_reported' \| 'provider_reported' \| 'user_entered' \| 'benchmark_estimated' \| 'modeled' \| null`	—	Updated provenance of the delivered activity metrics.
broadcastDetails	`object`	—	Updated broadcast delivery details.
outOfHomeDetails	`object`	—	Updated out-of-home delivery details.
printDetails	`object`	—	Updated print delivery details.
eventDetails	`object`	—	Updated event delivery details.
podcastDetails	`object`	—	Updated podcast delivery details.
prArticleDetails	`object`	—	Updated PR article delivery details.
contentHref	`string (URL) \| null`	—	URL to the original content (max 2,048 characters).
viewsCount	`integer \| null`	—	Manual view count override (non-negative integer).
likeCount	`integer \| null`	—	Manual like count override (non-negative integer).
replyCount	`integer \| null`	—	Manual reply count override (non-negative integer).

Response#

Returns { data, _meta } with the result.

Content link changes reset metrics

Changing the contentLink triggers a metric refresh. Previous metric snapshots are preserved but the latest values will update.

DELETE /v1/activities/:id#

Permanently delete an activity and its associated records.

bash

DELETE /v1/activities/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Activity identifier to delete.

Response#

Returns { data, _meta } with the result.

Destructive action

Deleting an activity permanently removes all linked metrics, costs, creator associations, and notes. This action cannot be undone.

POST /v1/activities/content-link/connect#

Connect a social media post URL to an activity for automatic metric tracking.

bash

POST /v1/activities/content-link/connect
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02",
  "platform": "instagram",
  "content_url": "..."
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to connect the content link to.
platform	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	Required	Social media platform for this content.
contentUrl	`string`	Required	URL to the social media content (max 2,048 characters).

Response#

Returns { data, _meta } with the result.

Metric refresh

Connecting a content link triggers an immediate metric fetch for the linked post.

POST /v1/activities/content-link/disconnect#

Disconnect a content link from an activity, stopping automatic metric tracking.

bash

POST /v1/activities/content-link/disconnect
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to disconnect the content link from.

Response#

Returns { data, _meta } with the result.

GET /v1/activities/creators#

List creators linked to an activity with pagination.

bash

GET /v1/activities/creators?page_index=0&page_size=25&organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization identifier.
activityId	`string (UUID)`	Required	Activity identifier to list creators for.

Response#

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

GET /v1/activities/creators/count#

Count the number of creators linked to an activity.

bash

GET /v1/activities/creators/count?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
activityId	`string (UUID)`	Required	Activity identifier to count creators for.

Response#

Returns { count, _meta }.

POST /v1/activities/:id/creators#

Associate a creator with an activity.

bash

POST /v1/activities/:id/creators
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02",
  "creator_id": "9b4c2e78-1a53-4f6d-b8e9-0c7a5d3f1e04"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to link.
creatorId	`string (UUID)`	Required	Creator identifier to link.

Response#

Returns { data, _meta } with the result.

DELETE /v1/activities/:id/creators/:creatorId#

Remove a creator association from an activity.

bash

DELETE /v1/activities/:id/creators/:creatorId
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to unlink from.
creatorId	`string (UUID)`	Required	Creator identifier to unlink.

Response#

Returns { data, _meta } with the result.

Cascading deletion

Unlinking a creator removes all cost records associated with that creator on this activity.

POST /v1/activities/costs#

Add a cost line item with net amount, currency, category, creator attribution, tax breakdown, and booking reference.

bash

POST /v1/activities/costs
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02",
  "amount": "150.00",
  "category_id": "...",
  "currency": "..."
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to add the cost to.
amount	`number`	Required	Cost amount (must be greater than zero, max 100M).
categoryId	`string (UUID)`	Required	Reusable cost category identifier.
currency	`string`	Required	ISO 4217 currency code, e.g. "USD", "NZD" (exactly 3 characters).
description	`string \| null`	—	Optional description of this cost line item (max 1,000 characters).
creatorId	`string (UUID) \| null`	—	Creator this cost is attributed to.
grossAmount	`number \| null`	—	Gross booked cost before discounts and tax adjustments.
discountAmount	`number \| null`	—	Discount applied to the gross booked cost.
taxAmount	`number \| null`	—	Tax amount recorded for the cost.
bookingReference	`string \| null`	—	Provider booking or insertion-order reference.

Response#

Returns { data, _meta } with the result.

Auto-linking

If the activity has exactly one linked creator, the cost is automatically attributed to that creator.

PATCH /v1/activities/costs/:id#

Update a cost line item's net, gross, discount, and tax amounts, category, creator attribution, description, or booking reference.

bash

PATCH /v1/activities/costs/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Cost record identifier to update.
amount	`number`	—	Updated cost amount (must be greater than zero, max 100M).
categoryId	`string (UUID)`	—	Updated reusable cost category identifier.
description	`string \| null`	—	Updated description (max 1,000 characters).
creatorId	`string (UUID) \| null`	—	Updated creator attribution.
grossAmount	`number \| null`	—	Gross booked cost before discounts and tax adjustments.
discountAmount	`number \| null`	—	Discount applied to the gross booked cost.
taxAmount	`number \| null`	—	Tax amount recorded for the cost.
bookingReference	`string \| null`	—	Provider booking or insertion-order reference.

Response#

Returns { data, _meta } with the result.

DELETE /v1/activities/costs/:id#

Remove a cost line item from an activity.

bash

DELETE /v1/activities/costs/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Cost record identifier to delete.

Response#

Returns { data, _meta } with the result.

GET /v1/activities/metrics/confidence#

Assess the statistical confidence of an activity's metrics.

bash

GET /v1/activities/metrics/confidence?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
startDate	`string \| null`	—	Start date for confidence calculation window.
endDate	`string \| null`	—	End date for confidence calculation window.

Response#

Returns { data, _meta } with the result.

GET /v1/activities/sparklines#

Fetch sparkline chart data for one or more activities.

bash

GET /v1/activities/sparklines?activity_ids=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
activityIds	`Array<string (UUID)>`	Required	Array of activity identifiers to fetch sparkline data for.

Response#

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

GET /v1/activities/:id#

Retrieve a single activity by ID with full details.

bash

GET /v1/activities/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Activity identifier.

Response#

Returns { data, _meta } with the result.