Conversion sources#

Manage conversion sources (HDYHAU surveys, UTM links, etc.) that attribute conversions to marketing activities.

Authentication required

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

GET /v1/conversion-sources#

List conversion sources with pagination, search, and sorting.

bash

GET /v1/conversion-sources?page_index=0&page_size=25&organization_id=org_123
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.

Response#

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

Underlying SDK method: bw.conversionSources.list(params)

GET /v1/conversion-sources/:id#

Retrieve a single conversion source by ID.

bash

GET /v1/conversion-sources/:id
Authorization: Bearer {token}

Parameters#

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

Response#

Returns { data } with the result.

Underlying SDK method: bw.conversionSources({ id })

POST /v1/conversion-sources#

Create a new conversion source with a marketing channel category for tracking attribution.

bash

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

{
  "organization_id": "org_123",
  "name": "My Campaign",
  "type": "instagram_post",
  "category": "..."
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
name	`string`	Required	Conversion source name.
type	`'hdyhau' \| 'promo_code' \| 'tracking_link'`	Required	Attribution method type.
category	`'organic_social' \| 'podcast' \| 'events' \| 'paid' \| 'referral' \| 'other'`	Required	Marketing channel category.
channel	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| null`	—	Social media platform for this conversion source.
creatorId	`string (UUID)`	—	Creator associated with this source.
campaignId	`string (UUID)`	—	Campaign associated with this source.
code	`string`	—	Promo code or tracking code (max 255 characters).
url	`string (URL)`	—	Tracking URL for link-based attribution (max 2,048 characters).

Response#

Returns { data } with the result.

Underlying SDK method: bw.conversionSources.create(params)

PATCH /v1/conversion-sources/:id#

Update a conversion source attribution type, category, social media channel, creator or campaign association, promo code, or tracking URL.

bash

PATCH /v1/conversion-sources/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Conversion source identifier to update.
name	`string`	—	Updated name (1-255 characters).
type	`'hdyhau' \| 'promo_code' \| 'tracking_link'`	—	Updated attribution type.
category	`'organic_social' \| 'podcast' \| 'events' \| 'paid' \| 'referral' \| 'other'`	—	Updated category.
channel	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| null`	—	Updated social media platform.
creatorId	`string (UUID) \| null`	—	Updated creator association.
campaignId	`string (UUID) \| null`	—	Updated campaign association.
code	`string \| null`	—	Updated promo/tracking code (max 255 characters).
url	`string (URL) \| null`	—	Updated tracking URL (max 2,048 characters).
isActive	`boolean`	—	Whether this source is active.

Response#

Returns { data } with the result.

Underlying SDK method: bw.conversionSources.update(params)

DELETE /v1/conversion-sources/:id#

Permanently delete a conversion source and disassociate its conversions.

bash

DELETE /v1/conversion-sources/:id
Authorization: Bearer {token}

Parameters#

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

Response#

Returns { data } with the result.

Underlying SDK method: bw.conversionSources.delete(params)

Cascading effect

Deleting a conversion source removes the source attribution from all linked conversions. The conversion records themselves are preserved.