Skip to main content
POST
This endpoint requires authentication. Include your Bearer token in the Authorization header.

​
Description

​
Mode 1: Add by Source ID (royaltySourceId)

Add a specific source variant by its UUID.

​
Mode 2: Add by Source Name (sourceName)

Add a source by name. The system automatically selects the current variant (the one with no end date, or the most recent if all have end dates). Note: The system will automatically associate additional variants as needed when processing royalty files with different date ranges.

​
Required Role

  • admin or owner role within the tenant

​
Business Rules

  • Must provide either royaltySourceId OR sourceName (not both)
  • Source must have public=true and isActive=true to be associated
  • Cannot add duplicate associations
  • Association is automatically set to isActive=true on creation

​
Side Effects

  • Triggers regeneration of tenant’s sales data query cache
  • Updates tenant-specific BigQuery query configurations
Authorization:
  • Required role: admin or higher

​
Code Examples

Authorizations

​
Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Body

application/json
​
royaltySourceId
string

UUID of a specific royalty source variant to associate. Use this OR sourceName, not both.

Example:

"src-1"

​
sourceName
string

Name of the source to associate ALL variants of (case-insensitive). Use this OR royaltySourceId, not both. Example: "africori", "alterk", "spotify"

Example:

"alterk"

​
settings
object

Tenant-specific settings for this source

Example:
​
replacements
object

Field mapping/replacement rules

Example:

Response

Tenant source association created

Association between a tenant and a royalty source. Note: The composite key is (TenantId, RoyaltySourceId).

​
TenantId
integer

Tenant ID (automatically set from authenticated user)

Example:

1

​
RoyaltySourceId
string

Royalty source ID

Example:

"src-1"

​
isActive
boolean
default:true

Whether this source association is active for the tenant

Example:

true

​
settings
object

Tenant-specific settings for this source

Example:
​
replacements
object

Tenant-specific field replacements/mappings

Example:
​
fileCount
integer
default:0

Number of files processed for this tenant-source association

Example:

42

​
lastProcessedAt
string<date-time> | null

Timestamp of the most recently processed file

Example:

"2026-03-04T14:30:00.000Z"

​
lastProcessedFileId
string<uuid> | null

ID of the most recently processed file

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
settingsUpdatedAt
string<date-time> | null

When tenant-specific settings were last modified

​
settingsUpdatedBy
string | null

TenantUserId who last updated the settings

​
royaltySource
object