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.
activityId	`string (UUID)`	—	Filter by activity identifier.
role	`'person' \| 'community' \| 'brand_partner'`	—	Filter by creator role.

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
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	—	Filter by activity identifier.
role	`'person' \| 'community' \| 'brand_partner'`	—	Filter by creator role.
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.

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.

Creators#

GET /v1/creators#

Parameters#

Response#

GET /v1/creators/stats#

Parameters#

Response#

GET /v1/creators/:id#

Parameters#

Response#

POST /v1/creators#

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#