Introduction
Chordal's InstantClear™ API enables approved platforms to quickly launch a synchronization licensing product, and offer fractionally owned commercial songs. Our API is made available in multiple tiers, based on how a user plans to integrate it. This documentation provides a full overview of how one might interact with the API, ranging from simple music pulls to full white-labeled user experience. (Available in the Enterprise tier).
Authenticating requests
To authenticate requests, include an Authorization
header with the value "Bearer {YOUR_AUTH_KEY}"
.
All authenticated endpoints are marked with a requires authentication
badge in the documentation below.
Clients are provided with signed JSON Web Tokens that the platform verify for every request that a client makes.
InstantClear Templates
List all of the InstantClear templates associated to my company’s account.
GET v1/licensing/preclearedPrograms
requires authentication
Example request:
const url = new URL(
"https://api.chordal.com/v1/licensing/preclearedPrograms"
);
const params = {
"name": "Euphoria",
"order_by": "name",
"sort_type": "asc",
"page": "2",
"per_page": "20",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.chordal.com/v1/licensing/preclearedPrograms';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'name' => 'Euphoria',
'order_by' => 'name',
'sort_type' => 'asc',
'page' => '2',
'per_page' => '20',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.chordal.com/v1/licensing/preclearedPrograms'
params = {
'name': 'Euphoria',
'order_by': 'name',
'sort_type': 'asc',
'page': '2',
'per_page': '20',
}
headers = {
'Authorization': 'Bearer {YOUR_AUTH_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
Example response (200):
{
"data": [
{
"id": 1,
"name": "Program Name",
"description": "A brief description of the program.",
"media": "TV and Streaming",
"territory": "United States",
"term": "1 Year",
"duration": "Up to 0:60",
"subscription_starts_at": "2025-03-21T12:00:00Z",
"subscription_ends_at": "2026-03-21T12:00:00Z",
"usage_starts_at": "2025-03-21T12:00:00Z",
"usage_ends_at": "2026-03-21T12:00:00Z",
"payment_deadline_at": "2026-03-21T12:00:00Z",
"created_at": "2025-03-21T12:00:00Z"
}
],
"links": {
"first": "https://api.chordal.com/v1/licensing/preclearedPrograms?page=1",
"last": "https://api.chordal.com/v1/licensing/preclearedPrograms?page=10",
"prev": null,
"next": "https://api.chordal.com/v1/licensing/preclearedPrograms?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 10,
"path": "https://api.chordal.com/v1/licensing/preclearedPrograms",
"per_page": 15,
"to": 15,
"total": 150
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Licenses
Deliver license confirmations back to Chordal. If your InstantClear program is using the FLAT rate type, this will be delivering individual usage confirmations at the per-license rate specified in precleared_program_per_use_fee_id. If your InstantClear program is using the METERED rate type, this will be delivering usage confirmations based on a variable rate determined in each accounting period, or the: total_reported_royalties. The rate type for your InstantClear program is configured by a Chordal account manager before integrating with the Licensing API.
POST v1/licensing/projects/{project_id/tracks/{track_id}/licenses
requires authentication
Example request:
const url = new URL(
"https://api.chordal.com/v1/licensing/projects/1/tracks/10/licenses"
);
const headers = {
"Authorization": "Bearer {YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"brief_title": "Upbeat, emotional electronic tracks",
"links": [
"http:\/\/Ac.A{2,}:t$\/i"
],
"total_reported_royalties": 1000,
"period_starts": "2024-10-01",
"period_ends": "2024-12-31",
"external_id": "\"EXT-12345\"",
"metadata": {
"key": "value"
}
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.chordal.com/v1/licensing/projects/1/tracks/10/licenses';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'brief_title' => 'Upbeat, emotional electronic tracks',
'links' => [
'http://Ac.A{2,}:t$/i',
],
'total_reported_royalties' => 1000,
'period_starts' => '2024-10-01',
'period_ends' => '2024-12-31',
'external_id' => '"EXT-12345"',
'metadata' => [
'key' => 'value',
],
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.chordal.com/v1/licensing/projects/1/tracks/10/licenses'
payload = {
"brief_title": "Upbeat, emotional electronic tracks",
"links": [
"http:\/\/Ac.A{2,}:t$\/i"
],
"total_reported_royalties": 1000,
"period_starts": "2024-10-01",
"period_ends": "2024-12-31",
"external_id": "\"EXT-12345\"",
"metadata": {
"key": "value"
}
}
headers = {
'Authorization': 'Bearer {YOUR_AUTH_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
Example response (200):
{
"data": {
"id": "SYNCHID-1.1",
"total_reported_royalties": 1000,
"external_id": "EXT-12345",
"period_starts": "2024-10-01",
"period_ends": "2024-12-31",
"created_at": "2024-09-25T12:34:56Z"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Projects
List all of the projects currently associated to an InstantClear template inside my company’s account.
GET v1/licensing/projects
requires authentication
Example request:
const url = new URL(
"https://api.chordal.com/v1/licensing/projects"
);
const params = {
"title": "Euphoria",
"license_status": "all-active",
"order_by": "title",
"sort_type": "asc",
"page": "2",
"per_page": "20",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.chordal.com/v1/licensing/projects';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'title' => 'Euphoria',
'license_status' => 'all-active',
'order_by' => 'title',
'sort_type' => 'asc',
'page' => '2',
'per_page' => '20',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.chordal.com/v1/licensing/projects'
params = {
'title': 'Euphoria',
'license_status': 'all-active',
'order_by': 'title',
'sort_type': 'asc',
'page': '2',
'per_page': '20',
}
headers = {
'Authorization': 'Bearer {YOUR_AUTH_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
Example response (200):
{
"data": [
{
"id": 1,
"title": "Project Title",
"slug": "project-title",
"short_title": "Short Title",
"description": "A brief description of the project.",
"preclearedProgram": {
"id": 1,
"name": "Program Name"
},
"tags": [
{
"id": 1,
"name": "Tag Name 1"
}
],
"image_url": "https://cdn.chordal.com/image.jpg",
"created_at": "2025-03-21T12:00:00Z"
}
],
"links": {
"first": "https://api.chordal.com/v1/licensing/projects?page=1",
"last": "https://api.chordal.com/v1/licensing/projects?page=10",
"prev": null,
"next": "https://api.chordal.com/v1/licensing/projects?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 10,
"path": "https://api.chordal.com/v1/licensing/projects",
"per_page": 15,
"to": 15,
"total": 150
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
POST v1/licensing/projects
requires authentication
Example request:
const url = new URL(
"https://api.chordal.com/v1/licensing/projects"
);
const headers = {
"Authorization": "Bearer {YOUR_AUTH_KEY}",
"Content-Type": "multipart/form-data",
"Accept": "application/json",
};
const body = new FormData();
body.append('title', 'Euphoria');
body.append('description', 'A brief description of the project.');
body.append('short_title', 'Euphoria');
body.append('precleared_program_id', '1');
body.append('image_url', 'https://cdn.chordal.com/image.jpg');
body.append('tags[]', 'tag1');
body.append('image', document.querySelector('input[name="image"]').files[0]);
fetch(url, {
method: "POST",
headers,
body,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.chordal.com/v1/licensing/projects';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
'Content-Type' => 'multipart/form-data',
'Accept' => 'application/json',
],
'multipart' => [
[
'name' => 'title',
'contents' => 'Euphoria'
],
[
'name' => 'description',
'contents' => 'A brief description of the project.'
],
[
'name' => 'short_title',
'contents' => 'Euphoria'
],
[
'name' => 'precleared_program_id',
'contents' => '1'
],
[
'name' => 'image_url',
'contents' => 'https://cdn.chordal.com/image.jpg'
],
[
'name' => 'tags[]',
'contents' => 'tag1'
],
[
'name' => 'image',
'contents' => fopen('/tmp/phpbAmllJ', 'r')
],
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.chordal.com/v1/licensing/projects'
files = {
'title': (None, 'Euphoria'),
'description': (None, 'A brief description of the project.'),
'short_title': (None, 'Euphoria'),
'precleared_program_id': (None, '1'),
'image_url': (None, 'https://cdn.chordal.com/image.jpg'),
'tags[]': (None, 'tag1'),
'image': open('/tmp/phpbAmllJ', 'rb')}
payload = {
"title": "Euphoria",
"description": "A brief description of the project.",
"short_title": "Euphoria",
"precleared_program_id": 1,
"image_url": "https:\/\/cdn.chordal.com\/image.jpg",
"tags": [
"tag1",
"tag2"
]
}
headers = {
'Authorization': 'Bearer {YOUR_AUTH_KEY}',
'Content-Type': 'multipart/form-data',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, files=files)
response.json()
Example response (200):
{
"data": {
"id": 1,
"title": "Project Title",
"slug": "project-title",
"short_title": "Short Title",
"description": "A brief description of the project.",
"preclearedProgram": {
"id": 1,
"name": "Program Name"
},
"tags": [
{
"id": 1,
"name": "Tag Name 1"
}
],
"image_url": "https://cdn.chordal.com/image.jpg",
"created_at": "2025-03-21T12:00:00Z"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
DELETE v1/licensing/projects/{id}
requires authentication
Example request:
const url = new URL(
"https://api.chordal.com/v1/licensing/projects/6"
);
const headers = {
"Authorization": "Bearer {YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "DELETE",
headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.chordal.com/v1/licensing/projects/6';
$response = $client->delete(
$url,
[
'headers' => [
'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.chordal.com/v1/licensing/projects/6'
headers = {
'Authorization': 'Bearer {YOUR_AUTH_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('DELETE', url, headers=headers)
response.json()
Example response (204):
Empty response
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Tracks
List all the tracks associated to a project.
GET v1/licensing/projects/{project_id}/tracks
requires authentication
Example request:
const url = new URL(
"https://api.chordal.com/v1/licensing/projects/1/tracks"
);
const params = {
"title": "Imagine",
"isrc": "USRC17607839",
"iswc": "T-123.456.789-0",
"order_by": "title",
"sort_type": "asc",
"page": "2",
"per_page": "20",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.chordal.com/v1/licensing/projects/1/tracks';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'title' => 'Imagine',
'isrc' => 'USRC17607839',
'iswc' => 'T-123.456.789-0',
'order_by' => 'title',
'sort_type' => 'asc',
'page' => '2',
'per_page' => '20',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.chordal.com/v1/licensing/projects/1/tracks'
params = {
'title': 'Imagine',
'isrc': 'USRC17607839',
'iswc': 'T-123.456.789-0',
'order_by': 'title',
'sort_type': 'asc',
'page': '2',
'per_page': '20',
}
headers = {
'Authorization': 'Bearer {YOUR_AUTH_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
Example response (200):
{
"data": [
{
"id": 1,
"isrc": "USRC17607839",
"iswc": "T-123.456.789-0",
"title": "Track Title",
"year": 2020,
"release_date": "2020-05-20",
"language_code": "en",
"version_type": "original" | "cover" | "remix",
"mix_type": "mixed" | "instrumental" | "acapella" | "clean" | "radio",
"structure": "has-build" | "consistent",
"key": "C major" | "C minor",
"tempo": 120,
"energy_level": "high" | "medium" | "low" | "variable",
"emotional_tone": "bright-uplifting" | "bright-focused" | "bright-emotional" | "dark-emotional" | "dark-focused" | "dark-disturbing",
"recognizability": 0-1000,
"artists": [
{
"id": 1,
"name": "Artist One"
}
],
"albums": [
{
"id": 1,
"title": "Album One"
}
],
"genres": [
{
"id": 1,
"name": "Pop"
}
],
"subgenres": [
{
"id": 1,
"name": "Indie Pop"
}
],
"moods": [
{
"id": 1,
"name": "Happy"
}
],
"instruments": [
{
"id": 1,
"name": "Guitar"
}
],
"creativeKeywords": [
{
"id": 1,
"name": "Uplifting"
}
],
"lyricMoods": [
{
"id": 1,
"name": "Sad"
}
],
"lyricThemes": [
{
"id": 1,
"name": "Ambition"
}
],
"lyrics_summary": "A summary of the lyrics",
"image_url": "https://cdn.chordal.com/image.jpg",
"audio_url": "https://cdn.chordal.com/audio.mp3",
"duration": 180,
"stems": [
{
"id": 101,
"title": "Guitar Stem",
"instrument": "Guitar",
"audio_url": "https://cdn.chordal.com/stems/guitar.mp3",
"duration": 180
},
]
}
}
],
"links": {
"first": "https://api.chordal.com/v1/licensing/projects/1/tracks?page=1",
"last": "https://api.chordal.com/v1/licensing/projects/1/tracks?page=5",
"prev": null,
"next": "https://api.chordal.com/v1/licensing/projects/1/tracks?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 5,
"path": "https://api.chordal.com/v1/licensing/projects/1/tracks",
"per_page": 15,
"to": 15,
"total": 75
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
GET v1/licensing/projects/{project_id}/{model_type}/{model_id}/download
requires authentication
Example request:
const url = new URL(
"https://api.chordal.com/v1/licensing/projects/1/tracks/10/download"
);
const params = {
"track_quality": "hi-res",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"track_quality": "hi-res"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://api.chordal.com/v1/licensing/projects/1/tracks/10/download';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'track_quality' => 'hi-res',
],
'json' => [
'track_quality' => 'hi-res',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.chordal.com/v1/licensing/projects/1/tracks/10/download'
payload = {
"track_quality": "hi-res"
}
params = {
'track_quality': 'hi-res',
}
headers = {
'Authorization': 'Bearer {YOUR_AUTH_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.json()
Example response (200):
Binary data - The file
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.