Creators#

Manage creators (influencers) with social media accounts across six platforms.

Authentication required

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

GET /v1/creators#

Retrieve a paginated list of creators for a workspace, ordered by name, totals, or efficiency.

bash

GET /v1/creators?page_index=0&page_size=25&workspace_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).
workspaceId	`string (UUID)`	Required	Workspace identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`'name' \| 'createdAt' \| 'activitiesCount' \| 'totalFollowersCount' \| 'impressions' \| 'engagement' \| 'spend' \| 'cpe' \| 'cpm'`	—	Creator field to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.
dateFrom	`string`	—	Earliest date to include, as YYYY-MM-DD in the workspace timezone.
dateTo	`string`	—	Latest date to include, as YYYY-MM-DD in the workspace timezone. Use the same date as dateFrom for a single day.
activityId	`string (UUID)`	—	Filter by activity identifier.
role	`'person' \| 'community' \| 'brand_partner' \| 'own_brand'`	—	Filter by creator role. Creator lists leave out your own brand unless role is own_brand.

Response#

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

GET /v1/creators/stats#

Aggregate statistics for creators matching the given filters.

bash

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

Parameters#

Name	Type	Required	Description
dateFrom	`string`	—	Earliest date to include, as YYYY-MM-DD in the workspace timezone.
dateTo	`string`	—	Latest date to include, as YYYY-MM-DD in the workspace timezone. Use the same date as dateFrom for a single day.
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	—	Filter by activity identifier.
role	`'person' \| 'community' \| 'brand_partner' \| 'own_brand'`	—	Filter by creator role. Creator lists leave out your own brand unless role is own_brand.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).

Response#

Returns { data, _meta } with the result.

GET /v1/creators/:id#

Retrieve a single creator by ID with full details and social accounts.

bash

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

Parameters#

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

Response#

Returns { data, _meta } with the result.

POST /v1/creators#

Create a new creator (influencer) within a workspace. Required: workspaceId, name. Optional: email, role (person/community/brand_partner), country (2-letter ISO code), notes.

bash

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

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
name	`string`	Required	Creator display name.
email	`string \| null`	—	Creator contact email.
role	`'person' \| 'community' \| 'brand_partner' \| null`	—	Creator role: "person", "community", or "brand_partner".
country	`string \| null`	—	Two-letter ISO 3166-1 country code.
notes	`string \| null`	—	Private notes about this creator (max 2,000 characters).

Response#

Returns { data, _meta } with the result.

POST /v1/creators/own-brand#

Get the record for your own brand as a poster, creating it the first time. Connect your brand's own social accounts to it and Brandwave adds each new post as an activity posted by your brand. Link it to an activity to record something your brand posted itself. It never appears in creator lists unless you filter by the own_brand role.

bash

POST /v1/creators/own-brand
Authorization: Bearer {token}
Content-Type: application/json

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace whose own brand to open.

Response#

Returns { data, _meta } with the result.

PATCH /v1/creators/:id#

Update a creator profile including role, country, and private notes.

bash

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

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Creator identifier to update.
name	`string`	—	Updated creator name (1-255 characters).
email	`string \| null`	—	Updated contact email.
role	`'person' \| 'community' \| 'brand_partner' \| null`	—	Updated role: "person", "community", or "brand_partner".
country	`string \| null`	—	Updated two-letter ISO 3166-1 country code.
notes	`string \| null`	—	Updated private notes (max 2,000 characters).

Response#

Returns { data, _meta } with the result.

DELETE /v1/creators/:id#

Permanently delete a creator and all associated data.

bash

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

Parameters#

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

Response#

Returns { data, _meta } with the result.

Destructive action

Deleting a creator removes all social account links, activity associations, and notes. This action cannot be undone.

Link a social profile URL or username to an existing creator in an authorized Brandwave workspace for marketing measurement. Adds a Brandwave association and may start background collection of public profile details and metrics. Public social profiles discovered in the profile biography may also be linked and collected. Supports Instagram, YouTube, TikTok, X/Twitter, LinkedIn, and Reddit. Reuses an existing association; retrying failed collection may start another background job. Returns a connection receipt and any collection-delay warning, not completed metrics. Does not authenticate as the social account owner, modify the social profile, publish posts, or send messages.

bash

POST /v1/creators/social-accounts/connect
Authorization: Bearer {token}
Content-Type: application/json

{
  "creator_id": "9b4c2e78-1a53-4f6d-b8e9-0c7a5d3f1e04",
  "platform": "instagram",
  "profile_url": "..."
}

Parameters#

Name	Type	Required	Description
creatorId	`string (UUID)`	Required	Creator identifier to connect the account to.
platform	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	Required	Social media platform.
profileUrl	`string`	Required	Profile URL or username for the social media account (max 2,048 characters).

Response#

Returns { data, _meta } with the result.

Supported platforms

Pass a platform field: 'instagram', 'youtube', 'tiktok', 'twitter', 'linkedin', or 'reddit'.

Disconnect a social media account from a creator.

bash

DELETE /v1/creators/:creatorId/social-accounts/:platform/:accountId
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
creatorId	`string (UUID)`	Required	Creator identifier to disconnect the account from.
accountId	`string (UUID)`	Required	Social media account identifier to disconnect.
platform	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	Required	Social media platform.

Response#

Returns { data, _meta } with the result.

GET /v1/creators/metrics#

Fetch metrics for a single creator including activity counts, follower totals, impressions, engagement, spend, CPM, and CPE.

bash

GET /v1/creators/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&creator_id=9b4c2e78-1a53-4f6d-b8e9-0c7a5d3f1e04
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
creatorId	`string (UUID)`	Required	Creator identifier to get metrics for.

Response#

Returns { data, _meta } with the result.

GET /v1/creators/metrics/history#

Fetch a creator's follower count, impressions, engagement, spend, CPM, and CPE over time with a configurable lookback window.

bash

GET /v1/creators/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&creator_id=9b4c2e78-1a53-4f6d-b8e9-0c7a5d3f1e04
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
creatorId	`string (UUID)`	Required	Creator identifier.
daysBack	`integer`	—	Number of days of history to return (1-365).

Response#

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

Creators#

GET /v1/creators#

Parameters#

Response#

GET /v1/creators/stats#

Parameters#

Response#

GET /v1/creators/:id#

Parameters#

Response#

POST /v1/creators#

Parameters#

Response#

POST /v1/creators/own-brand#

Parameters#

Response#

PATCH /v1/creators/:id#

Parameters#

Response#

DELETE /v1/creators/:id#

Parameters#

Response#

POST /v1/creators/social-accounts/connect#

Parameters#

Response#

DELETE /v1/creators/:creatorId/social-accounts/:platform/:accountId#

Parameters#

Response#

GET /v1/creators/metrics#

Parameters#

Response#

GET /v1/creators/metrics/history#

Parameters#

Response#