A release is an album, EP, or single. Releases contain one or more tracks and various metadata. Use the
/content/release/save
resource to create or edit releases. Specifically, this resource enables you to do the
following:
Unless otherwise stated, the Revelator API does not support partial updates. When editing an object, the existing values of any omitted parameters will be deleted or overwritten, according to the designated behavior for a null value for that parameter. Consequently, we recommend you always query the object you want to edit and modify the JSON object to avoid partial update problems.
Before detailing the request body, please review these important rules regarding UPCs and the creation of compilation releases.
Currently, a single trackId
can only be associated with one release at a time.
If you need to include the same underlying recording (i.e., the same ISRC) on multiple releases (e.g., a single and a
later album), you must treat it as a new track for each release. This means you should create a new track entity
(which will generate a new, unique trackId
) for each release it appears on.
We are actively working on removing this constraint to allow a single track entity to be associated with multiple releases. This documentation will be updated when that functionality is available.
To ensure data integrity and prevent content conflicts, UPCs must be unique across the entire Revelator system.
UPCs used in sandbox account can be used again in production account.
A compilation is a release that features multiple primary artists. Our system has specific validation rules to correctly identify and process these releases.
Artists Must Exist and Be Provided For a compilation release to validate properly, all contributors (especially
primary artists using roleId = 49
) must be provided as an object containing their existing artistId
. You cannot
create new artists implicitly within a compilation release payload.
Compilation Validation Logic Our system determines if a release is a “Various Artists” compilation based on the
presence of a main artistId
at the release level and the count of primary artist contributors (roleId = 49
)
across the entire release (at both the release and track levels).
artistId
at the release level: The release is treated as a standard release by a
primary artist. You will receive an error if you also include more than four primary artist contributors
(roleId = 49
).artistId
at the release level: The release is treated as a “Various Artists”
compilation. You will receive an error if you include less than four primary artist contributors
(roleId = 49
). This ensures the release meets the criteria for a compilation./content/release/save
Parameter | Type | Description |
---|---|---|
name required | string | Title of the Release.
|
releaseId optional | integer | ID for the existing release you want to edit. This ID was returned in the response when the release was created.
|
artistName optional | string | Name of the release’s primary artist/band.
|
artistId optional | integer | ID for an existing artist to assign as the primary artist for the release.
|
releasesLocals required | array of objects | Release name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the release name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules). Parameter is mandatory even if the array is empty.
|
releasesLocals.name required | string | Name in the indicated language. |
releasesLocals.version optional | string | Version in the indicated language. |
releasesLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
artistLocals.name required | string | Name in the indicated language. |
artistLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
contributors required | array of objects | Additional key artists who should be given top level credit. Do not provide individual band member names. For example, “The Beatles” and, not John Lennon, Paul McCartney, George Harrison and Ringo Starr.
|
contributors.contributorId optional | UUID | ID for an existing contributor.
|
contributors.roleId required | integer | The artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles .
|
contributors.artist required | object | The contributing artist. Unlike all other artists in Revelator, contributing artists with any role other than Primary Artist, Featuring, or Remixer do not require external artist IDs. In other words, contributing artists with the roles Primary Artist, Featuring, or Remixer require Apple and Spotify IDs (same as primary artists); contributing artists with other roles do not require these IDs (they are optional). See Artist Object |
version optional | string | Title version. For example, Remastered or Deluxe edition. Typically omitted unless the release is a new version of a previously released release. |
copyrightP required | string | The product copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The product copyright holder is the person or entity that owns the exclusive rights to the complete product, including both sound recording and artwork. |
copyrightC required | string | The sound recording copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The sound recording copyright holder is the person or entity that owns the exclusive rights to the sound recording. |
hasRecordLabel optional | boolean |
|
labelName optional | string |
|
labelId optional | integer | ID for an existing label to assign to the release.
|
artistExternalIds optional | array of objects | An array of external DSP profile IDs for the main primary artist of the release. This structured array is the required method for providing DSP profile IDs. See the comprehensive guide at Managing External Artist IDs. |
artistAppleId DEPRECATED | string | (DEPRECATED) This field is obsolete. Provide Apple Music profile IDs using the release.artistExternalIds array with distributorStoreId: 1 instead. See Managing External Artist IDs. |
artistSpotifyId DEPRECATED | string | (DEPRECATED) This field is obsolete. Provide Spotify profile IDs using the release.artistExternalIds array with distributorStoreId: 9 instead. See Managing External Artist IDs. |
previouslyReleased optional | boolean |
|
upc optional | integer | UPC/EAN/JAN code for the release.
|
releaseDate optional | string | Official date the release was previously released in the ISO format YYYY-MM-DD
|
primaryMusicStyleId required | integer | The primary music style ID for the release. See Music Style ID. |
secondaryMusicStyleId optional | integer | The secondary music style ID for the release. See Music Style ID. |
languageId required | integer | Language ID for the release’s meta data. This is not the language of the songs/lyrics, but the language of the information provided in this API request. Lookup up the languageId using the GET /common/lookup/languages resource. English is 1. |
description optional | string | Release description. |
tracks required | array of objects | Tracks for the release.
|
image optional | object | Cover image for the release.
|
Parameter | Type | Description |
---|---|---|
name optional | string | Name of the artist.
|
artistId optional | integer | ID for an existing artist.
|
artistExternalIds optional | array of objects | External IDs for the artist. See the comprehensive guide at Managing External Artist IDs. |
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
artistLocals.name required | string | Name in the indicated language. |
artistLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
Parameter | Type | Description |
---|---|---|
filename required | string | Name of the file, including the extension. |
fileId required | string | The ID for a file that has already been uploaded to the Revelator server. See Uploading Files |
Used within the trackRecordingVersions.audioFiles
array.
Parameter | Type | Description |
---|---|---|
audioId required | string | The ID for a file that has already been uploaded to the Revelator server. See Uploading Files |
audioFilename required | string | Name of the audio file, including the extension. |
fileFormat required | string |
|
Parameter | Type | Description |
---|---|---|
name optional | string | Title of the track.
|
trackId optional | integer | The ID of an existing track to associate with the release. This ID was returned when the track was created.
|
artistName optional | string | Name of the track’s primary artist/band.
|
artistId optional | integer | ID for an existing artist to assign as the primary artist for the track.
|
tracksLocals optional | array of objects | Track name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the track name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
tracksLocals.name required | string | Name in the indicated language. |
tracksLocals.version optional | string | Version in the indicated language. |
tracksLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
artistLocals.name required | string | Name in the indicated language. |
artistLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
contributors required | array of objects | Additional key artists who should be given top level credit. Do not provide individual band member names. For example, “The Beatles” and, not John Lennon, Paul McCartney, George Harrison and Ringo Starr.
|
contributors.contributorId optional | UUID | ID for an existing contributor.
|
contributors.roleId required | integer | The artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles .
|
contributors.artist required | object | The contributing artist. Unlike all other artists in Revelator, contributing artists with any role other than Primary Artist, Featuring, or Remixer do not require external artist IDs. In other words, contributing artists with the roles Primary Artist, Featuring, or Remixer require Apple and Spotify IDs (same as primary artists); contributing artists with other roles do not require these IDs (they are optional). See Artist Object |
languageId required | integer | Language ID for the track’s lyrics. Lookup up the languageId using the GET /common/lookup/languages endpoint . English is 1. |
version optional | string | Version of the track. For example, Remix or Bonus Track. |
explicit required | boolean | Be sure that your user interface indicates the importance of properly identifying this content. Misidentifying this content can result in your distribution being disabled. Should be true when the song contains any of the following:
|
trackType required | integer | One of the following:
|
trackProperties required | array of integers | One or multiple of the following:
|
artistExternalIds optional | array of objects | An array of external DSP profile IDs for the main primary artist of the release. This structured array is the required method for providing DSP profile IDs. See the comprehensive guide at Managing External Artist IDs. |
artistAppleId DEPRECATED | string | (DEPRECATED) This field is obsolete. Provide Apple Music profile IDs using the track.artistExternalIds array with distributorStoreId: 1 instead. See Managing External Artist IDs. |
artistSpotifyId DEPRECATED | string | (DEPRECATED) This field is obsolete. Provide Spotify profile IDs using the track.artistExternalIds array with distributorStoreId: 9 instead. See Managing External Artist IDs. |
copyrightP optional | string | The product copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The product copyright holder is the person or entity that owns the exclusive rights to the complete product, including both sound recording and artwork. |
copyrightC optional | string | The sound recording copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The sound recording copyright holder is the person or entity that owns the exclusive rights to the sound recording. |
primaryMusicStyleId optional | integer | The primary music style ID for the track. See Music Style ID. |
secondaryMusicStyleId optional | integer | The secondary music style ID for the track. See Music Style ID. |
previewStartSeconds optional | integer | Preview/Clip Start Time. Indicate where your clip should start when people preview your track. If no value is entered, your clip will start at the 15th second. |
composerContentsDTO required | array of objects | A list of publishing contributors(composers) for the track . The same composer cannot be added with the same role more than once. The uniqueness of each entry is validated by the combination of the composer’s identity (composerName or composerId ) and their roleId . |
composerContentsDTO.composerName optional | string | Name of the composer.
|
composerContentsDTO.composerId optional | integer | ID for an existing composer to assign to the track.
|
composerContentsDTO.rightsId required | integer | Publishing type. One of the following:
|
composerContentsDTO.roleId required | integer | A role associated with the composer. Look up roleIds with GET /common/lookup/contributorRoles . Only roles from contributorRoleGroupId = 4 are relevant for composers. |
composerContentsDTO.share optional | string | Share percentage for the composer. The total percentage for all composers must be 100%. Note that this has nothing to do with contract splits, and publisher royalties are never paid through the Revelator platform. |
composerContentsDTO.publisherName optional | string | Name of the publisher to assign to the composer.
|
composerContentsDTO.publisherId optional* | integer | ID for an existing publisher to assign to the composer.
publisherId to 0 (along with providing a publisherName) to create a new publisher whenever no existing publisher with the provided name exists. Omitting this parameter will cause the publisher (name and ID) to be null. |
composerContentsDTO.composersLocals optional | array of objects | Composer name in different languages. If name or languageId are omitted, the object will be ignored. |
composerContentsDTO.composersLocals.name optional | string | Name in the indicated language. |
composerContentsDTO.composersLocals.version optional | string | Version in the indicated language. |
composerContentsDTO.composersLocals.languageId optional | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
lyrics optional | string | Lyrics for the track. Note that not all stores accept lyrics. |
compositions optional | array of objects | An array of Composition objects representing the underlying musical works for the track. This field is relevant for tracks of all types (Original, Cover, Public Domain) as it describes the fundamental composition. Important behavior during track type change: When updating a track and changing its trackType from 2 (Cover song) to 1 (Original song) or 3 (Public domain song), any existing compositions array will be automatically cleared. This indicates that for these trackType changes, the compositions data cannot be directly carried over or updated in the same request; it will be cleared. |
compositions.originalTitle optional | string | The original title of the musical work/composition. |
compositions.originalComposers optional | string | The names of the original composer(s) of the musical work. |
compositions.originalRecordingArtist optional | string | The name(s) of the artist(s) who originally recorded this musical work. |
compositions.sourceAlbumTitle optional | string | The title of the original album from which this musical work originates, if applicable. |
compositions.sourceMaterialTitle optional | string | The title of the original source material (e.g., film, play, book) from which this musical work originates, if applicable. |
compositions.iswc optional | string | International Standard Musical Work Code (ISWC). A unique, international identifier for musical works. Format: T followed by 10 digits (e.g., T1234567890). Issued by national or regional ISWC agencies. |
compositions.url optional | string | A URL relevant to the composition (e.g., a link to its original publisher or details). |
compositions.notes optional | string | Internal notes or comments related to the composition. |
compositions.isPaid optional | boolean | Indicates if royalties/payments for this composition have been settled or paid. |
isrc optional | string | This field is part of the old Track Recording model. See New track recording model for more information. ISRC code for the track. Hyphens and spaces will be automatically removed, and letters will be automatically capitalized.
|
wav optional | object | This field is part of the old Track Recording model. See New track recording model for more information. Audio file for the track in WAV format.
|
trackRecordingVersions optional | array of objects | This field is part of the new Track Recording model. See New track recording model for more information. If provided, this list needs to have
|
trackRecordingVersions.recordingVersionType required | integer | Type of the track version.
|
trackRecordingVersions.isrc required | string | A valid ISRC code for the track version.
null if the ISRC should be generated automatically (during distribution). |
trackRecordingVersions.audioFiles required | array of objects | When creating a new track, this array must contain a single object with a WAV (1 ) or a FLAC (2 ) fileFormat .
When editing an existing track:
|
With the release of support for Dolby Atmos, we have updated the track object adequately. The old model is going to remain supported with the goal of backwards compatibility; however, we strongly advise adapting to this new model (even if not utilizing Dolby Atmos).
New model (Supports Dolby Atmos)
Track object includes the following properties:
trackRecordingVersions[]
isrc
recordingVersionType
trackRecordingVersions.audioFiles[]
- audioFiles.audioId
- audioFiles.audioFilename
- audioFiles.fileFormat
Old model (Does not support Dolby Atmos)
Track object includes the following properties:
isrc
wav
or flac
Only one of the two models should be used, failiure to do so will result in an error.
Refer to the track object table for coprehensive information on these fields
All files must be uploaded before being associated with a track or a release. This goes for both audio and image assets.
/media/audio/upload
Uploads WAV or FLAC audio files.
A recent change requires all audio files to be longer than 2 seconds. Invalid audio files will be rejected.
Content-type for this request must be multipart/form-data
Form Field | Type | Description |
---|---|---|
file required | binary | The audio file to upload |
Field | Type | Description |
---|---|---|
fileId | string | The ID of the uploaded file that’s going to be used to reference it across the application. |
filename | string | The filename of the uploaded file. |
/media/audio/upload/wav
Uploads WAV audio files.
This endpoint has the same request, response, and requirements as POST /media/audio/upload
.
The file
field in the Form Data should contain the WAV audio file.
/media/audio/upload/flac
Uploads FLAC audio files.
This endpoint has the same request, response, and requirements as POST /media/audio/upload
.
The file
field in the Form Data should contain the FLAC audio file.
/media/image/upload
Content-type for this request must be multipart/form-data
If the uploaded image is a PNG and the cover
query parameter is set to true
, the image will be automatically
converted to JPG.
Parameter | Type | Description |
---|---|---|
cover optional | boolean | Is the image going to be used as a cover art |
Form Field | Type | Description |
---|---|---|
file required | binary | The image file to upload |
fileId - string |
/media/audio/pullexternal/wav
An alternative way to upload files by providing a publicly available URL. This endpoint can be useful if you don’t want to handle the file upload yourself or if the asset is already hosted elsewhere.
A recent change requires all audio files to be longer than 2 seconds. Invalid audio files will be rejected.
You can use expiring links as a measure of security, as long as the file is accessible within the timeframe when this endpoint is invoked.
Parameter | Type | Description |
---|---|---|
externalUrl required | string | A valid URL to a publicly available audio file. |
filename required | string | The name of the file. You must include the file extension (e.g., my-track.wav ). |
Field | Type | Description |
---|---|---|
fileId | string | The ID of the uploaded file that’s going to be used to reference it across the application. |
filename | string | The filename of the uploaded file. |
Use the following endpoints to retrieve release data.
By default, these endpoints will return all releases the user has permissions to view, not just the releases in the user’s account. A parent account user will receive all releases in every child.
In response you will receive releaseTypeId
which is automatically set based on provided data across release and it’s
tracks.
1
- Album2
- Single4
- EPSome endpoint will return additionalCounters
. This object contains number of release types that were not included in
retuned list but match searched conditions.
/content/release/all
Retrieves paginated list of all releases the user has permissions to view.
Parameter | Type | Description |
---|---|---|
pageNumber optional | integer | The page number of the results to retrieve. Default is 1 . |
pageSize optional | integer | The number of items to return per page. Requires pageNumber query parameter to work properly. |
orderByProperty optional | string | The property to sort the results by. Available options:
|
orderByDescending optional | boolean | If false , orders the results in ascending order. If true or omitted, orders in descending order. |
searchText optional | string | A search term to filter releases by name. The search is case-insensitive. |
selectAll optional | boolean | If true, the response will only contain an array of releaseId values for all matching releases. |
fromDate optional | date-time | Filters for releases created on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
toDate optional | date-time | Filters for releases created on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
releaseFromDate optional | date-time | Filters for releases with a releaseDate on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
releaseToDate optional | date-time | Filters for releases with a releaseDate on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
musicStyles optional | array | An array of Music Style IDs to filter releases associated with any of the specified music styles. |
languages optional | array | An array of language IDs to filter releases. |
labels optional | array | An array of label IDs to filter releases. |
stores optional | array | An array of store IDs to filter releases distributed to any of the specified stores. |
enterprises optional | array | An array of enterprise IDs to filter releases. Only relevant for parent account users. |
releaseTypes optional | array | An array of release type IDs (1 : Album, 2 : Single, 4 : EP) to filter releases. |
artists optional | array | An array of artist IDs. If provided, returns only releases where the provided artist ID is the main primary artist of the release. |
upc optional | string | Filters for a release with a specific UPC. The match must be exact. |
/content/release/all/summary
Retrieves a summary of all releases the user has permissions to view.
Parameter | Type | Description |
---|---|---|
searchText optional | string | A search term to filter releases by name. The search is case-insensitive. |
fromDate optional | date-time | Filters for releases created on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
toDate optional | date-time | Filters for releases created on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
releaseFromDate optional | date-time | Filters for releases with a releaseDate on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
releaseToDate optional | date-time | Filters for releases with a releaseDate on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS). |
musicStyles optional | array | An array of Music Style IDs to filter releases associated with any of the specified music styles. |
languages optional | array | An array of language IDs to filter releases. |
labels optional | array | An array of label IDs to filter releases. |
stores optional | array | An array of store IDs to filter releases distributed to any of the specified stores. |
enterprises optional | array | An array of enterprise IDs to filter releases. Only relevant for parent account users. |
releaseTypes optional | array | An array of release type IDs (1 : Album, 2 : Single, 4 : EP) to filter releases. |
artists optional | array | An array of artist IDs. If provided, returns only releases where the provided artist ID is the main primary artist of the release. |
/content/release/{releaseId}
Retrieves the release with the releaseId
specified in the URL path.
Upcoming Change: The SpotifyId
, AppleId
, and RdioId
fields on the Track
object are deprecated and will be
removed in a future update.
Please use the new ReleaseTracks
field for DSP identifiers going forward. This new structure provides a more
consistent and scalable way to associate tracks with external DSP identifiers across releases.
Example of the new ReleaseTracks
field within the Track object:
{
// Existing fields
"tracks": [
{
// Existing fields
"releaseTracks": [
{
"releaseId": 0,
"spotifyId": "string",
"appleId": 0,
"rdioId": "string",
"deezerId": "string"
}
]
}
]
}
An artist is a metadata entity that is referenced in assets (releases and tracks).
Due to DSP requirements, an artist cannot be listed as a primary artist twice, or listed as both a primary artist and a featuring artist on the same track or release.
The Revelator API prohibits this scenario with an error message when attempting to set an artist as both the main
primary artist (indicated with the artistId
and artistName
) as well as a contributor with the role of primary or
featuring.
/artists
Creates new or edits existing artists in the account associated with the access token.
For Child Account implementation models, you have the option to run requests in a child account while authenticated as a parent account user. See Running Requests in Child Accounts.
Parameter | Type | Description |
---|---|---|
name optional | string | Name of the artist.
|
artistId optional | integer | ID for an existing artist.
|
artistExternalIds optional | array of objects | External IDs for the artist for each store. Each supported store should have one or zero entries.
|
artistExternalIds.profileId required | string | External ID for the artist at the specified store.
|
artistExternalIds.distributorStoreId required | string | Revelator ID for the store. Currently supported for:
|
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
artistLocals.name required | string | Name in the indicated language. |
artistLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
image optional | object | The image representing the artist. See File Object. |
additionalContacts optional | array of objects | Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section. |
activeFromDate optional | string | The specific date when the artist began their activity. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SS). |
activeToDate optional | string | The specific date when the artist ended their activity (or null if still active). ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SS). |
firstName optional | string | Legal first name of the artist. Must consist only of Unicode letters, hyphens (-), single quotes (’), or dots (.). Must have a total length between 1 and 100 characters (inclusive). |
middleName optional | string | Legal middle name(s) of the artist. |
lastName optional | string | Legal last name of the artist. Must consist only of Unicode letters, hyphens (-), single quotes (’), or dots (.). Must have a total length between 1 and 100 characters (inclusive). |
isni optional | string | The International Standard Name Identifier (ISNI) for the artist. Must be exactly 16 alphanumeric characters, where the last character can also be ‘X’. |
artistLabels optional | array of objects | An array of objects, each representing an association with a Label. See nested fields below for structure and requirements. |
artistLabels.labelId required | integer | The ID of an existing Label to associate with the artist. |
artistLabels.contractStartYear required | string | The start date of the contract between the artist and this label. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ). |
artistLabels.contractEndYear optional | string | The end date of the contract between the artist and this label. If provided, must be after contractStartYear . ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ). |
Use the following endpoints to retrieve artist data.
For Child Account implementation models, you have the option to run requests in a child account while authenticated as a parent account user. See Running Requests in Child Accounts.
/artists
Retrieves list of all artists in the account.
Parameter | Type | Description |
---|---|---|
labels optional | array | An array of label IDs to filter artists associated with any of the specified labels. |
name optional | string | Name of artist, case-sensitive, exact match. |
isni optional | string | Filters artists by their International Standard Name Identifier (ISNI). |
contributorGroupId optional | integer | Filters artists who have contributed to tracks/releases using a role that belongs to the specified Contributor Role Group ID. Refer to /common/lookup/ContributorRolesGroups for available group IDs. |
/artists/summary
Retrieves a summary of all artists in the account.
/artists/{artistId}
Retrieves the artist with the artistId
specified in the URL path.
Parameter | Type | Description |
---|---|---|
labels optional | array | One or more labels associated with artists |
name optional | string | Name of artist |
/content/artist/all
Retrieves paginated list of all artists in the account.
Parameter | Type | Description |
---|---|---|
labels optional | array | An array of label IDs to filter artists associated with any of the specified labels. |
name optional | string | Filters artists by name (case-insensitive, exact match). |
fromDate optional | date-time | Filters for artists created on or after the provided date. Expected format: YYYY-MM-DDTHH:MM:SS (e.g., ISO 8601 without timezone). |
toDate optional | date-time | Filters for artists created on or before the provided date. Expected format: YYYY-MM-DDTHH:MM:SS (e.g., ISO 8601 without timezone). |
musicStyles optional | array | An array of music style IDs to filter artists associated with any of the specified music styles. |
isni optional | string | Filters artists by their International Standard Name Identifier (ISNI). |
contributorGroupId optional | integer | Filters artists who have contributed to tracks/releases using a role that belongs to the specified Contributor Role Group ID. Refer to /common/lookup/ContributorRolesGroups for available group IDs. |
pageNumber optional | integer | The page number of the results to retrieve. Default is 1 . |
pageSize optional | integer | The number of items per page. Default is a system-defined value. Requires pageNumber query parameter to work properly. |
orderByProperty optional | string | The property to sort the results by. Available options: - artistId - isni - name - firstName - middleName - lastname |
orderByDescending optional | boolean | If true or omitted, orders the results in descending order. If false , orders in ascending order. |
searchText optional | string | Allows to search by client’s name. |
External Artist IDs (also known as profile IDs) are identifiers used by DSPs (Digital Service Providers) to group an artist’s content under a single profile. Providing these IDs is crucial for preventing situations where artists with the same name are merged or a single artist’s catalog is split across multiple profiles.
This is managed through the artistExternalIds
array, which can be provided in the following contexts:
Currently, providing external artist IDs is supported for:
distributorStoreId: 1
)distributorStoreId: 9
)distributorStoreId: 68
)distributorStoreId: 309
& 310
)artistExternalIds
The artistExternalIds
is an array of objects. Each object links a profileId
(the artist’s ID on the DSP) with a
distributorStoreId
(our internal ID for the DSP).
Parameter | Type | Description |
---|---|---|
artistExternalIds optional | array of objects | An array of objects, each representing an external ID for the artist at a specific store. Each supported store should have one or zero entries. |
artistExternalIds.profileId required | string | The artist’s profile ID at the specified store. To find this ID, go to the artist’s page at the store and copy the unique identifier from the URL. |
artistExternalIds.distributorStoreId required | integer | The Revelator ID for the store. See the “Supported DSPs” callout above for current values. |
Always provide a profileId
if one exists for the artist. If the artist is new to a DSP, you should omit the entry
for that DSP from the artistExternalIds
array. Each DSP has different behavior when an artist’s profile ID is not
provided:
1
): A new profile will be generated during distribution.9
): A new profile will be generated when a release goes live.68
): SoundCloud will attempt to map the artist to an existing profile or create a new one if
unsuccessful. Please contact Support if you notice your release mapped to the wrong page.309
& 310
): Meta will attempt to map the artist to an existing profile. New profiles cannot be created
automatically. Please contact Support if you notice your release mapped to the wrong page.Profiles for Facebook Audio Library (309
) and Facebook Rights Manager (310
) are connected. When you assign an
artist’s profile for one, we will automatically create the other. When updating, you must provide the same profileId
for both distributorStoreId: 309
and distributorStoreId: 310
simultaneously.
If a profileId
for an artist has already been generated by a DSP, you must retrieve and use it for all subsequent
releases. Failing to provide the existing ID will cause a second, duplicate profile to be generated for the artist,
splitting their catalog.
Before distributing a new release for an artist who was previously new to a DSP, follow these steps:
GET /content/artist/{artistId}
endpoint. The response will include
the most up-to-date artistExternalIds
array, including any newly generated IDs. See
Artist Object.artistExternalIds
array in your POST /content/release/save
request.Do not continuously poll our system for new IDs. Only run the GET request immediately before distributing a new release
that requires the ID. A profileId
may never be generated for various reasons (e.g., a Spotify release does not go
live).
A publisher is a metadata entity that is referenced in assets (releases and tracks).
/content/publisher/save
Creates a new publisher or updates an existing one. The target enterprise for the operation can be specified if the authenticated user has appropriate parent/child account permissions.
When a new Publisher is created implicitly as part of saving a Release or Track, its enterpriseId
will automatically
be set to match the enterpriseId
of that Release or Track.
This is a change from previous behavior where the new publisher would inherit the enterpriseId
of the currently
authenticated user’s session. This new behavior ensures that implicitly created publishers are correctly associated with
the enterprise context of the asset they are first introduced with.
When managing Publishers directly via the /content/publisher/save
endpoint, you have more explicit control over the
enterpriseId
as described in the parameters for this endpoint.
When assigning existing contact, only contactId
on additionalContacts
object is required.
Parameter | Type | Description |
---|---|---|
publisherId optional | Integer | ID for an existing publisher. Required when editing publisher, should be ommited or set to 0 when creating new publisher. |
name required | string | Full name of the publisher. |
ipiCae optional | string | IPI (Interested Parties Information) - CAE (Composer, Author, and Publisher) number. Exactly 9 digits (IPI) or 11 digits (CAE). Unique across publishers and composers (writers) in the same tenant if present. Used to identify publishers across rights organizations. |
image optional | object | The image representing the publisher. See File Object. |
image.fileId required | string | The ID of the previously uploaded file. Required when image object is present. |
image.filename required | string | Name of the previously uploaded file with extension. |
proAffiliations optional | array of objects | A list detailing the Performance Rights Organizations (PROs) affiliations. |
proAffiliations.proId required | integer | Our internal ID linking to the mechanicalPros entity. |
proAffiliations.memberId required | string | Unique ID issued by PRO. Unique across composers and publishers for the same tenant. |
additionalContacts optional | array of objects | Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section. |
website optional | string | Publisher’s website. |
countryId optional | integer | Country where this publisher administers publishing rights and collects royalties. |
enterpriseId optional | integer | Specifies the target enterprise ID for the publisher.
|
Use the following endpoints to retrieve publisher data.
/content/publisher/all
Retrieves a paginated list of all publishers in the account, with options for sorting and searching.
Parameter | Type | Description |
---|---|---|
pageNumber optional | integer | The page number of the results to retrieve. Default is 1 . |
pageSize optional | integer | The number of items to return per page. Default is 24 . Requires pageNumber query parameter to work properly. |
orderByProperty optional | string | The property to sort the results by. Available options:
|
orderByDescending optional | boolean | If false , orders the results in ascending order. If true or omitted, orders in descending order. |
searchText optional | string | A search term to filter publishers by name. The search is case-insensitive. |
/content/publisher/all/summary
Retrieves a summarized list of publishers. Allows for searching and limiting results.
Parameter | Type | Description |
---|---|---|
query optional | string | A search term to filter publishers by name. The search is case-insensitive. |
limit optional | integer | The maximum number of summary items to return. |
/content/publisher/{publisherId}
Retrieves detailed information for a specific publisher by its publisherId
.
Parameter | Type | Description |
---|---|---|
publisherId | integer | The unique ID of the publisher to retrieve. |
A composer(writer) is a metadata entity that is referenced in assets (releases and tracks).
/content/composer/save
Creates a new composer or updates an existing one. The target enterprise for the operation can be specified if the authenticated user has appropriate parent/child account permissions.
When a new Composer is created implicitly as part of saving a Release or Track, its enterpriseId
will automatically be
set to match the enterpriseId
of that Release or Track.
This is a change from previous behavior where the new composer would inherit the enterpriseId
of the currently
authenticated user’s session. This new behavior ensures that implicitly created composers are correctly associated with
the enterprise context of the asset they are first introduced with.
When managing Composers directly via the /content/composer/save
endpoint, you have more explicit control over the
enterpriseId
as described in the parameters for this endpoint.
When assigning existing contact, only contactId
on additionalContacts
object is required.
Parameter | Type | Description |
---|---|---|
composerId optional | Integer | ID for an existing composer. Required when editing composer, should be ommited or set to 0 when creating new composer. |
name required | string | Composer’s full legal name exactly as shown on official paperwork (e.g., contracts, copyright registrations). |
isni optional | string | The International Standard Name Identifier (ISNI) for the artist. Must be exactly 16 alphanumeric characters, where the last character can also be ‘X’. |
ipiCae optional | string | IPI (Interested Parties Information) - CAE (Composer, Author, and Publisher) number. Exactly 9 digits (IPI) or 11 digits (CAE). Unique across publishers and composers (writers) in the same tenant if present. Used to identify publishers across rights organizations. |
biography optional | string | Composers’s biography. |
countryOfResidenceId optional | integer | The country in which this contributor officially resides. Used for legal and payout requirements. |
composersLocals optional | array of objects | A list of Composer’s name in different languages. |
composersLocals.name required | string | Composer’s name in the indicated language. |
composersLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Updates to local names are based on this field. If you don’t inclde object with specified languageId entry with it will be deleted. |
image optional | object | The image representing the publisher. See File Object. |
image.fileId required | string | The ID of the previously uploaded file. Required when image object is present. |
image.filename required | string | Name of the previously uploaded file with extension. |
proAffiliations optional | array of objects | A list detailing the Performance Rights Organizations (PROs) affiliations. |
proAffiliations.proId required | integer | Our internal ID linking to the mechanicalPros entity. |
proAffiliations.memberId required | string | Unique ID issued by PRO. Unique across composers and publishers for the same tenant. |
additionalContacts optional | array of objects | Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section. |
enterpriseId optional | integer | Specifies the target enterprise ID for the composer.
|
Use the following endpoints to retrieve composer data.
/content/composer/all
Retrieves a paginated list of all composers in the account, with options for sorting and searching.
Parameter | Type | Description |
---|---|---|
pageNumber optional | integer | The page number of the results to retrieve. Default is 1 . |
pageSize optional | integer | The number of items to return per page. |
orderByProperty optional | string | The property to sort the results by. Available options:
|
orderByDescending optional | boolean | If false , orders the results in ascending order. If true or omitted, orders in descending order. |
searchText optional | string | A search term to filter composer by name. The search is case-insensitive. |
/content/composer/all/summary
Retrieves a summarized list of composers. Allows for searching and limiting results.
Parameter | Type | Description |
---|---|---|
query optional | string | A search term to filter composers by name. The search is case-insensitive. |
limit optional | integer | The maximum number of summary items to return. |
enterpriseId optional | integer | Used when executing from parent account to return composers from intended child account. |
/content/composer/{composerId}
Retrieves detailed information for a specific composer by its composerId
.
Parameter | Type | Description |
---|---|---|
composerId | integer | The unique ID of the composer to retrieve. |