Create Royalty Source (Admin)

curl --request POST \
  --url https://api.royalti.io/sources/admin \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Spotify",
  "label": "Spotify",
  "type": "DSP",
  "format": "csv",
  "public": true,
  "isActive": true,
  "startDate": "2020-01-01",
  "endDate": "2025-01-01",
  "dataQuery": {
    "type": "bigquery",
    "dataset": "royalty_data"
  },
  "fileNameFormat": "royalty_{date}.csv",
  "schema": "artist_name,track_name,streams,revenue",
  "delimiter": ",",
  "tableNameFormat": "royalty_{tenant}",
  "headerRows": 1,
  "defaultCurrency": "USD",
  "defaultFeeRate": 0.015,
  "feeDescription": "<string>",
  "feeEmbeddedInQuery": false,
  "parentSourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.royalti.io/sources/admin"

payload = {
    "name": "Spotify",
    "label": "Spotify",
    "type": "DSP",
    "format": "csv",
    "public": True,
    "isActive": True,
    "startDate": "2020-01-01",
    "endDate": "2025-01-01",
    "dataQuery": {
        "type": "bigquery",
        "dataset": "royalty_data"
    },
    "fileNameFormat": "royalty_{date}.csv",
    "schema": "artist_name,track_name,streams,revenue",
    "delimiter": ",",
    "tableNameFormat": "royalty_{tenant}",
    "headerRows": 1,
    "defaultCurrency": "USD",
    "defaultFeeRate": 0.015,
    "feeDescription": "<string>",
    "feeEmbeddedInQuery": False,
    "parentSourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Spotify',
    label: 'Spotify',
    type: 'DSP',
    format: 'csv',
    public: true,
    isActive: true,
    startDate: '2020-01-01',
    endDate: '2025-01-01',
    dataQuery: {type: 'bigquery', dataset: 'royalty_data'},
    fileNameFormat: 'royalty_{date}.csv',
    schema: 'artist_name,track_name,streams,revenue',
    delimiter: ',',
    tableNameFormat: 'royalty_{tenant}',
    headerRows: 1,
    defaultCurrency: 'USD',
    defaultFeeRate: 0.015,
    feeDescription: '<string>',
    feeEmbeddedInQuery: false,
    parentSourceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.royalti.io/sources/admin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.royalti.io/sources/admin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Spotify',
    'label' => 'Spotify',
    'type' => 'DSP',
    'format' => 'csv',
    'public' => true,
    'isActive' => true,
    'startDate' => '2020-01-01',
    'endDate' => '2025-01-01',
    'dataQuery' => [
        'type' => 'bigquery',
        'dataset' => 'royalty_data'
    ],
    'fileNameFormat' => 'royalty_{date}.csv',
    'schema' => 'artist_name,track_name,streams,revenue',
    'delimiter' => ',',
    'tableNameFormat' => 'royalty_{tenant}',
    'headerRows' => 1,
    'defaultCurrency' => 'USD',
    'defaultFeeRate' => 0.015,
    'feeDescription' => '<string>',
    'feeEmbeddedInQuery' => false,
    'parentSourceId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.royalti.io/sources/admin"

	payload := strings.NewReader("{\n  \"name\": \"Spotify\",\n  \"label\": \"Spotify\",\n  \"type\": \"DSP\",\n  \"format\": \"csv\",\n  \"public\": true,\n  \"isActive\": true,\n  \"startDate\": \"2020-01-01\",\n  \"endDate\": \"2025-01-01\",\n  \"dataQuery\": {\n    \"type\": \"bigquery\",\n    \"dataset\": \"royalty_data\"\n  },\n  \"fileNameFormat\": \"royalty_{date}.csv\",\n  \"schema\": \"artist_name,track_name,streams,revenue\",\n  \"delimiter\": \",\",\n  \"tableNameFormat\": \"royalty_{tenant}\",\n  \"headerRows\": 1,\n  \"defaultCurrency\": \"USD\",\n  \"defaultFeeRate\": 0.015,\n  \"feeDescription\": \"<string>\",\n  \"feeEmbeddedInQuery\": false,\n  \"parentSourceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.royalti.io/sources/admin")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Spotify\",\n  \"label\": \"Spotify\",\n  \"type\": \"DSP\",\n  \"format\": \"csv\",\n  \"public\": true,\n  \"isActive\": true,\n  \"startDate\": \"2020-01-01\",\n  \"endDate\": \"2025-01-01\",\n  \"dataQuery\": {\n    \"type\": \"bigquery\",\n    \"dataset\": \"royalty_data\"\n  },\n  \"fileNameFormat\": \"royalty_{date}.csv\",\n  \"schema\": \"artist_name,track_name,streams,revenue\",\n  \"delimiter\": \",\",\n  \"tableNameFormat\": \"royalty_{tenant}\",\n  \"headerRows\": 1,\n  \"defaultCurrency\": \"USD\",\n  \"defaultFeeRate\": 0.015,\n  \"feeDescription\": \"<string>\",\n  \"feeEmbeddedInQuery\": false,\n  \"parentSourceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.royalti.io/sources/admin")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Spotify\",\n  \"label\": \"Spotify\",\n  \"type\": \"DSP\",\n  \"format\": \"csv\",\n  \"public\": true,\n  \"isActive\": true,\n  \"startDate\": \"2020-01-01\",\n  \"endDate\": \"2025-01-01\",\n  \"dataQuery\": {\n    \"type\": \"bigquery\",\n    \"dataset\": \"royalty_data\"\n  },\n  \"fileNameFormat\": \"royalty_{date}.csv\",\n  \"schema\": \"artist_name,track_name,streams,revenue\",\n  \"delimiter\": \",\",\n  \"tableNameFormat\": \"royalty_{tenant}\",\n  \"headerRows\": 1,\n  \"defaultCurrency\": \"USD\",\n  \"defaultFeeRate\": 0.015,\n  \"feeDescription\": \"<string>\",\n  \"feeEmbeddedInQuery\": false,\n  \"parentSourceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "src-3",
  "name": "Spotify",
  "label": "Spotify",
  "type": "DSP",
  "format": "csv",
  "public": true
}

{
  "status": "error",
  "message": "Invalid request parameters"
}

{
  "status": "error",
  "message": "Unauthorized"
}

{
  "status": "error",
  "message": "Internal server error"
}

POST

sources

admin

Create Royalty Source (Admin)

curl --request POST \
  --url https://api.royalti.io/sources/admin \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Spotify",
  "label": "Spotify",
  "type": "DSP",
  "format": "csv",
  "public": true,
  "isActive": true,
  "startDate": "2020-01-01",
  "endDate": "2025-01-01",
  "dataQuery": {
    "type": "bigquery",
    "dataset": "royalty_data"
  },
  "fileNameFormat": "royalty_{date}.csv",
  "schema": "artist_name,track_name,streams,revenue",
  "delimiter": ",",
  "tableNameFormat": "royalty_{tenant}",
  "headerRows": 1,
  "defaultCurrency": "USD",
  "defaultFeeRate": 0.015,
  "feeDescription": "<string>",
  "feeEmbeddedInQuery": false,
  "parentSourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.royalti.io/sources/admin"

payload = {
    "name": "Spotify",
    "label": "Spotify",
    "type": "DSP",
    "format": "csv",
    "public": True,
    "isActive": True,
    "startDate": "2020-01-01",
    "endDate": "2025-01-01",
    "dataQuery": {
        "type": "bigquery",
        "dataset": "royalty_data"
    },
    "fileNameFormat": "royalty_{date}.csv",
    "schema": "artist_name,track_name,streams,revenue",
    "delimiter": ",",
    "tableNameFormat": "royalty_{tenant}",
    "headerRows": 1,
    "defaultCurrency": "USD",
    "defaultFeeRate": 0.015,
    "feeDescription": "<string>",
    "feeEmbeddedInQuery": False,
    "parentSourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Spotify',
    label: 'Spotify',
    type: 'DSP',
    format: 'csv',
    public: true,
    isActive: true,
    startDate: '2020-01-01',
    endDate: '2025-01-01',
    dataQuery: {type: 'bigquery', dataset: 'royalty_data'},
    fileNameFormat: 'royalty_{date}.csv',
    schema: 'artist_name,track_name,streams,revenue',
    delimiter: ',',
    tableNameFormat: 'royalty_{tenant}',
    headerRows: 1,
    defaultCurrency: 'USD',
    defaultFeeRate: 0.015,
    feeDescription: '<string>',
    feeEmbeddedInQuery: false,
    parentSourceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.royalti.io/sources/admin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.royalti.io/sources/admin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Spotify',
    'label' => 'Spotify',
    'type' => 'DSP',
    'format' => 'csv',
    'public' => true,
    'isActive' => true,
    'startDate' => '2020-01-01',
    'endDate' => '2025-01-01',
    'dataQuery' => [
        'type' => 'bigquery',
        'dataset' => 'royalty_data'
    ],
    'fileNameFormat' => 'royalty_{date}.csv',
    'schema' => 'artist_name,track_name,streams,revenue',
    'delimiter' => ',',
    'tableNameFormat' => 'royalty_{tenant}',
    'headerRows' => 1,
    'defaultCurrency' => 'USD',
    'defaultFeeRate' => 0.015,
    'feeDescription' => '<string>',
    'feeEmbeddedInQuery' => false,
    'parentSourceId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.royalti.io/sources/admin"

	payload := strings.NewReader("{\n  \"name\": \"Spotify\",\n  \"label\": \"Spotify\",\n  \"type\": \"DSP\",\n  \"format\": \"csv\",\n  \"public\": true,\n  \"isActive\": true,\n  \"startDate\": \"2020-01-01\",\n  \"endDate\": \"2025-01-01\",\n  \"dataQuery\": {\n    \"type\": \"bigquery\",\n    \"dataset\": \"royalty_data\"\n  },\n  \"fileNameFormat\": \"royalty_{date}.csv\",\n  \"schema\": \"artist_name,track_name,streams,revenue\",\n  \"delimiter\": \",\",\n  \"tableNameFormat\": \"royalty_{tenant}\",\n  \"headerRows\": 1,\n  \"defaultCurrency\": \"USD\",\n  \"defaultFeeRate\": 0.015,\n  \"feeDescription\": \"<string>\",\n  \"feeEmbeddedInQuery\": false,\n  \"parentSourceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.royalti.io/sources/admin")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Spotify\",\n  \"label\": \"Spotify\",\n  \"type\": \"DSP\",\n  \"format\": \"csv\",\n  \"public\": true,\n  \"isActive\": true,\n  \"startDate\": \"2020-01-01\",\n  \"endDate\": \"2025-01-01\",\n  \"dataQuery\": {\n    \"type\": \"bigquery\",\n    \"dataset\": \"royalty_data\"\n  },\n  \"fileNameFormat\": \"royalty_{date}.csv\",\n  \"schema\": \"artist_name,track_name,streams,revenue\",\n  \"delimiter\": \",\",\n  \"tableNameFormat\": \"royalty_{tenant}\",\n  \"headerRows\": 1,\n  \"defaultCurrency\": \"USD\",\n  \"defaultFeeRate\": 0.015,\n  \"feeDescription\": \"<string>\",\n  \"feeEmbeddedInQuery\": false,\n  \"parentSourceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.royalti.io/sources/admin")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Spotify\",\n  \"label\": \"Spotify\",\n  \"type\": \"DSP\",\n  \"format\": \"csv\",\n  \"public\": true,\n  \"isActive\": true,\n  \"startDate\": \"2020-01-01\",\n  \"endDate\": \"2025-01-01\",\n  \"dataQuery\": {\n    \"type\": \"bigquery\",\n    \"dataset\": \"royalty_data\"\n  },\n  \"fileNameFormat\": \"royalty_{date}.csv\",\n  \"schema\": \"artist_name,track_name,streams,revenue\",\n  \"delimiter\": \",\",\n  \"tableNameFormat\": \"royalty_{tenant}\",\n  \"headerRows\": 1,\n  \"defaultCurrency\": \"USD\",\n  \"defaultFeeRate\": 0.015,\n  \"feeDescription\": \"<string>\",\n  \"feeEmbeddedInQuery\": false,\n  \"parentSourceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "src-3",
  "name": "Spotify",
  "label": "Spotify",
  "type": "DSP",
  "format": "csv",
  "public": true
}

{
  "status": "error",
  "message": "Invalid request parameters"
}

{
  "status": "error",
  "message": "Unauthorized"
}

{
  "status": "error",
  "message": "Internal server error"
}

This endpoint requires authentication. Include your Bearer token in the Authorization header.

Code Examples

const response = await fetch('https://api.royalti.io/sources/admin', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "name": "Spotify",
    "label": "Spotify",
    "type": "DSP",
    "format": "csv",
    "public": true,
    "isActive": true,
    "startDate": "2020-01-01",
    "endDate": "2025-01-01",
    "dataQuery": {
      "type": "bigquery",
      "dataset": "royalty_data"
    },
    "fileNameFormat": "royalty_{date}.csv",
    "schema": "artist_name,track_name,streams,revenue",
    "delimiter": ",",
    "tableNameFormat": "royalty_{tenant}",
    "headerRows": 1,
    "defaultCurrency": "USD",
    "defaultFeeRate": 0.015,
    "feeType": "sample-feeType",
    "feeDescription": "sample-feeDescription",
    "exchangeRateStrategy": "sample-exchangeRateStrategy",
    "feeEmbeddedInQuery": true,
    "parentSourceId": "sample-parentSourceId",
    "sourceCategory": "sample-sourceCategory"
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
  'https://api.royalti.io/sources/admin',
  headers={
    'Authorization': f'Bearer {token}'
  },
  json={"name":"Spotify","label":"Spotify","type":"DSP","format":"csv","public":true,"isActive":true,"startDate":"2020-01-01","endDate":"2025-01-01","dataQuery":{"type":"bigquery","dataset":"royalty_data"},"fileNameFormat":"royalty_{date}.csv","schema":"artist_name,track_name,streams,revenue","delimiter":",","tableNameFormat":"royalty_{tenant}","headerRows":1,"defaultCurrency":"USD","defaultFeeRate":0.015,"feeType":"sample-feeType","feeDescription":"sample-feeDescription","exchangeRateStrategy":"sample-exchangeRateStrategy","feeEmbeddedInQuery":true,"parentSourceId":"sample-parentSourceId","sourceCategory":"sample-sourceCategory"}
)

data = response.json()
print(data)

curl -X POST https://api.royalti.io/sources/admin \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Spotify","label":"Spotify","type":"DSP","format":"csv","public":true,"isActive":true,"startDate":"2020-01-01","endDate":"2025-01-01","dataQuery":{"type":"bigquery","dataset":"royalty_data"},"fileNameFormat":"royalty_{date}.csv","schema":"artist_name,track_name,streams,revenue","delimiter":",","tableNameFormat":"royalty_{tenant}","headerRows":1,"defaultCurrency":"USD","defaultFeeRate":0.015,"feeType":"sample-feeType","feeDescription":"sample-feeDescription","exchangeRateStrategy":"sample-exchangeRateStrategy","feeEmbeddedInQuery":true,"parentSourceId":"sample-parentSourceId","sourceCategory":"sample-sourceCategory"}'

Authorizations

Authorization

string

header

required

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

Body

application/json

name

string

required

Source name (will be normalized to lowercase)

Example:

"Spotify"

label

string

required

Display label

Example:

"Spotify"

type

string

required

Source type

Example:

"DSP"

format

string

required

File format

Example:

"csv"

public

boolean

default:true

Make source publicly available (default true)

Example:

true

isActive

boolean

default:true

Mark source as active (default true)

Example:

true

startDate

string<date> | null

Example:

"2020-01-01"

endDate

string<date> | null

Example:

"2025-01-01"

dataQuery

object | null

JSONB query configuration

Example:

{
  "type": "bigquery",
  "dataset": "royalty_data"
}

fileNameFormat

string | null

Example:

"royalty_{date}.csv"

schema

string | null

Text representation of schema

Example:

"artist_name,track_name,streams,revenue"

delimiter

string | null

Example:

","

tableNameFormat

string | null

Example:

"royalty_{tenant}"

headerRows

integer | null

Example:

1

defaultCurrency

string | null

Default currency code (e.g., USD, GBP)

Maximum string length: 3

Example:

"USD"

defaultFeeRate

number | null

Default fee rate as decimal (e.g., 0.015 = 1.5%)

Example:

0.015

feeType

enum<string> | null

Fee calculation type

Available options:

percentage,

fixed

feeDescription

string | null

Human-readable fee description

exchangeRateStrategy

enum<string> | null

Foreign exchange conversion strategy

Available options:

cte,

inline,

external_table

feeEmbeddedInQuery

boolean

default:false

Whether the fee is embedded in the SQL query

parentSourceId

string<uuid> | null

Parent source ID for versioned sources

sourceCategory

enum<string> | null

Source category

Available options:

aggregator,

dsp,

publisher,

label,

other

Response

Royalty source created successfully

string

Example:

"src-1"

name

string

Source name (automatically normalized to lowercase)

Example:

"spotify"

label

string

Display label for the source

Example:

"Spotify"

type

string

Source type (e.g., DSP, Publisher, Label)

Example:

"DSP"

format

string

File format (csv, excel, json, etc.)

Example:

"csv"

public

boolean

Whether this source is publicly available to all tenants

Example:

true

isActive

boolean

default:true

Whether this source is currently active

Example:

true

startDate

string<date> | null

Start date for source availability

Example:

"2020-01-01"

endDate

string<date> | null

End date for source availability

Example:

"2025-01-01"

dataQuery

object | null

deprecated

Deprecated. Legacy JSONB object containing query configurations. Use dedicated columns instead: salesDataQuery, royaltySumQuery, countSumQuery, metadataQuery.

Example:

{
  "type": "bigquery",
  "dataset": "royalty_data"
}

fileNameFormat

string | null

Template for expected file name format with period placeholders. Placeholders: {SALPER-FORMAT} (sale period), {ACCPER-FORMAT} (accounting period) Formats: YYYYMM, YYYY-MM, YYYY-MM-DD, MMM-YYYY, etc.

Example:

"{ORG}_Snap_{SALPER-YYYYMM}_Monthly-Sales.csv"

schema

string | null

Text representation of the file schema/structure

Example:

"artist_name,track_name,streams,revenue"

delimiter

string | null

Field delimiter for CSV files

Example:

","

tableNameFormat

string | null

Template for BigQuery table name with period placeholders (SALPER, ACCPER)

Example:

"merlin_snap_SALPER_ACCPER"

columnFormat

string | null

DSL for column semantic mappings. Defines how columns map to period types and formats. Format: ColumnName:TYPE-FORMAT;ColumnName2:TYPE-FORMAT;... Types: SALPER (sale period), ACCPER (accounting period), ISRC, UPC, CATNO, etc. Formats: YYYY-MM-DD, YYYYMM, YYYY-MM, etc.

Example:

"Start_Date:SALPER-YYYY-MM-DD;ISRC:ISRC"

headerRows

integer | null

Number of header rows to skip

Example:

1

fileInfo

object | null

Additional file metadata and configuration

salesDataQuery

string | null

Dedicated SQL query for BigQuery sales data view (extracted from dataQuery JSONB)

royaltySumQuery

string | null

SQL query for calculating royalty sum after file processing

countSumQuery

string | null

SQL query for calculating row count after file processing

metadataQuery

string | null

SQL query for extracting metadata from processed data

assetExtractionQuery

string | null

SQL query for extracting asset catalog items (by ISRC) from raw royalty data. Derived from source schema column mapping

productExtractionQuery

string | null

SQL query for extracting product catalog items (by UPC) from raw royalty data. Derived from source schema column mapping

defaultCurrency

string | null

Default currency code (e.g., USD, GBP). Overridable per-tenant via TenantRoyaltySource settings

Maximum string length: 3

Example:

"USD"

defaultFeeRate

number | null

Default fee rate as decimal (e.g., 0.015 = 1.5%). Overridable per-tenant

Example:

0.015

feeType

enum<string> | null

Fee calculation type

Available options:

percentage,

fixed

Example:

"percentage"

feeDescription

string | null

Human-readable fee description

Example:

"Merlin distribution fee"

exchangeRateStrategy

enum<string> | null

Foreign exchange conversion strategy used in SQL queries

Available options:

cte,

inline,

external_table

feeEmbeddedInQuery

boolean

default:false

Whether the fee multiplier is embedded in the SQL query (true) or applied externally (false)

parentSourceId

string<uuid> | null

Parent source ID for versioned sources (e.g., merlin_vevo variants)

sourceCategory

enum<string> | null

Source category for classification

Available options:

aggregator,

dsp,

publisher,

label,

other

Example:

"dsp"

​Code Examples

Authorizations

Body

Response

Code Examples