The documentation for the /finance/salereport/all
endpoint has been updated to include new query parameters for more granular filtering.
You can now filter sale reports by releaseId
, releaseIds
, trackId
, and trackIds
.
Please see the updated Sale Reports documentation for details.
/finance/salereport/all
The documentation for endpoints used to retrieve release information has been significantly updated. This includes adding comprehensive details for previously undocumented query parameters for filtering, sorting, and pagination on the /content/release/all
and /content/release/all/summary
endpoints.
We’ve also added explanations for system-derived fields like releaseTypeId
and additionalCounters
.
Please review the updated Retrieving Releases section for full details.
/content/release/all
/content/release/all/summary
/content/release/{releaseId}
We are introducing a new, more robust method for selecting specific contributor roles, particularly for composerContentsDTO
and contributors
, by using the contributorRoleGroupId
system.
While the old method of filtering roles by priority
will continue to work for now, we strongly recommend that you update your integrations to use the new contributorRoleGroupId
system. This new method is more reliable and will be the standard going forward.
The documentation has been updated to reflect this new recommendation. For more details, please see Adding/Editing Releases.
/content/release/save
/releases/audio
We’ve enhanced our data models to allow associating multiple contacts with Artists, Composers, and Publishers. This improvement enables more comprehensive contact management and better role-specific communications.
The additionalContacts
field has been added to:
This array field allows you to associate multiple contacts with each entity, each with their own role designation.
/artists
/artists/{artistId}
/content/artist/*
/content/composer/*
/content/publisher/*
We’re improving how active periods are tracked for Artist object by adding new fields.
ActiveFromDate
(datetime, optional): The specific date when the artist began their activityActiveToDate
(datetime, optional): The specific date when the artist ended their activity (or null if still active)/artists/{artistId}
/artists
/content/artist/{id}
/content/artist/save
/content/track/{id}
/content/track/save
/content/release/{id}
/content/release/save
The Artist object has been significantly enhanced with new fields for more comprehensive data management, including identity details, label associations, and contribution categorizations.
Please refer to the updated Artist documentation for full details:
/artists/{artistId}
/artists/summary
/artists
/content/artist/*
/content/release/*
/content/track/*
The documentation for the composerContentsDTO.roleId
(used when adding composer information to tracks) has been updated to clarify selection criteria. Relevant roles for composers are those with either Priority = 5
OR belonging to contributorRoleGroupId = 4
.
See the updated guidance in Adding/Editing Releases.
/content/release/save
/releases/audio
/api/enterprises/{enterpriseId}/releases/audio
The ComposerContentsDTO
object returned in API responses now includes a new composerImageId
field. This ID is derived from the image associated with the linked composer (composerId
) and provides a direct way to access the composer’s image.
/content/release/save
/releases/audio
/api/enterprises/{enterpriseId}/releases/audio
We’ve introduced new dedicated endpoints for creating, retrieving, and managing Composer information directly. This allows for more comprehensive and standalone composer data management.
The Composer object, accessible via these new endpoints, now includes a richer set of fields:
isni
, ipiCae
, countryOfResidenceId
, and proAffiliations
.worksCount
(number of associated tracks/releases), publishersCount
, contributorRoleIds
(based on their contributions), and creationDate
.Full details on the Composer model and these endpoints can be found in the new documentation:
/content/composer/save
/content/composer/all
/content/composer/{id}
This change affects any endpoint that returns or accepts a Contact object in its request or response body.
contactRoleId
(integer, optional): An identifier linking to the specific role of the contact (e.g., Billing Contact, Technical Contact)./artists/{artistId}
/content/artist/{id}
/accounting/contract/save
/content/release/{id}
/content/release/save
This change affects any endpoint that returns or accepts a Contributor object in its request or response. The Contributor model has been extended with a new field:
contributorRoleGroupId
(integer, optional): An identifier linking to the specific group role of the contributor./content/track/{id}
/content/release/{id}
/content/release/save
When a new Composer or Publisher is created implicitly during the process of saving a Release or Track (i.e., by providing new composer/publisher details within the release/track save payload), its enterpriseId
will now automatically be set to match the enterpriseId
of that Release or Track.
Previously, such implicitly created Composers/Publishers would inherit the enterpriseId
of the currently authenticated user’s session. This update ensures more accurate and contextually correct enterprise association for these entities from their point of creation within an asset.
For more details, see the updated notes in the Composer and Publisher documentation sections.
/api/enterprises/{enterpriseId}/releases/audio
/releases/audio
/api/enterprises/{enterpriseId}/releases/video
/releases/video
/content/release/save
/content/track/save
Endpoint was replaced with /whitelabel/check-email-domain
.
/whitelabel/{id}/check-email-domain
Description now can be changed after release is distributed. Before changes to that field were ignored.
/api/enterprises/{enterpriseId}/releases/audio
/api/enterprises/{enterpriseId}/releases/video
/releases/audio
/releases/video
/content/release/save
The /content/artist/all
endpoint response now includes additional fields for richer artist information, such as releasesCount
, musicStyles
, and creationDate
. This endpoint and its complete response structure are detailed in the updated documentation.
See Retrieving artists for full information.
/content/artist/all
We are introducing two new lookup endpoints to provide easier access to lists of Contributor Role Groups and Contact Roles.
/common/lookup/ContributorRolesGroups
/common/lookup/contactRoles
We’ve added new query parameters to artist endpoints:
options.isni
(string, optional): Filter results by a specific ISNIoptions.contributorGroupId
(integer, optional): Filter results by a specific Contributor Group ID/api/enterprises/{enterpriseId}/artists
/artists
/content/artist/all
We’ve improved the permissions
object with new properties that provide better control over enterprise access and account type specification. These enhancements will improve the user experience for accounts with access to multiple enterprises.
isDefault
(boolean): This property determines the default enterprise when a user has access to multiple enterprises under the same account type. When true
, this enterprise will be selected by default upon loginaccountType
(integer): This property specifies the type of account these permissions apply to./account/loginpartner
/partner/account/login
/accounting/contract/save
/accounting/contract/{id}
/accounting/contract/all
Endpoints for managing Publishers are now officially documented. The Publisher model has also been enhanced with new fields for richer data.
Please refer to the new documentation sections:
/content/publisher/all/summary
/content/publisher/{id}
/content/publisher/save
/content/publisher/all
The ContractTypeId
field is being removed from both the request body and the response body of the POST /accounting/contract/save
endpoint. This field was identified as unused and is being removed to simplify the contract management process.
/accounting/contract/save
2025-07-22
Parent enterprise users can now retrieve analytics data specifically for their child enterprises using the new optional targetEnterpriseId
query parameter.
Please refer to the updated Analytics documentation for more details on usage. Comprehensivee Analytics and Keymetrics
/analytics/{dataSet}/{aggregationDimension}
/analytics/revenue/metricsByDate
We’ve updated the royaltyToken
object structure to better represent digital asset information and streamline the data model.
Added Fields
assetName
(string): The name of the digital asset represented by the tokenassetVersion
(string): The version identifier for the digital assetRemoved Fields
track
(object): This nested object has been removed and its relevant data has been moved to the new fields/content/track/{id}
/content/release/{id}
/royaltyTokens
/royaltyTokens/{tokenId}
Added an optional payoutRate
parameter (integer, 1-100, defaults to 100) to the Royalty Token creation process. This field defines the percentage of royalties that will be transferred to the token.
POST /royaltyTokens
The documentation section for “Running Requests in Child Accounts” has been updated for clarity. It now includes a list of currently supported endpoints for this feature and notes that we plan to expand this capability in the future.
Please review the updated guidance here: Running Requests in Child Accounts
/api/enterprises/{enterpriseId}/<documented_path>
New fields include:
isCrypto
(boolean | null): Indicates if the report/statement is to be paid in cryptocurrency to an enterprise Royalty Pool balance (a balance reserved exclusively for payments related to Royalty Tokens).isSmartWalletPayee
(boolean): Indicates the payee is to be paid directly to their enterprise Smart Wallet 0x address./finance/salereport/all
/finance/salereport/{statementId}
Documentation has been updated for contacts management. Details can be found in the Adding/Editing Contacts section.
/contact/create
/contact/update
/contact
/contact/{id}
Documentation has been updated for client information retrieval. Details can be found in the Retrieving Client Information section.
/enterprise/clients/{enterpriseId}
/enterprise/clients/all
Documentation has been added for audio upload endpoints. Details can be found in the Uploading Files section.
/media/audio/upload
/media/audio/upload/wav
/media/audio/upload/flac
To enhance data quality and ensure proper crediting, we are introducing a new requirement: at least one contributor from
the “Production & Engineering Credits” contributor group (contributorRoleGroupId
= 3
) is now mandatory for all
releases submitted or updated via the affected endpoints.
The contributorRoleGroupId
for different contributors types can be checked on /common/lookup/contributorRoles
.
/content/release/save
2025-06-25
The WarningCount
field is being removed from the responses of the specified content release endpoints. Please update
your integrations to no longer expect or utilize this field to avoid any disruptions.
content/release/all
content/release/all/summary
content/release/{releaseId}
2025-06-25
To enhance data integrity and streamline operations, we will implement validation to prevent UPC re-use, ensuring unique identification across releases.
/content/release/save
2025-05-08
As part of an internal revamp of our validation architecture, we will remove these fields since they are no longer relevant. This change enables the creation of newer and more accurate validations while also allowing us to introduce new validations into production more quickly.
validationErrors.field
validationErrors.value
validationErrors.errorCode
/distribution/release/{releaseId}/validate
2025-05-04
Removal of deprecated fields Last June, we introduced support for TikTok’s new Scanning service (TTS)— and it’s officially going live. This feature
lets users set Monetize
or BlockAccess
policies on tracks used in UGC videos.
To comply with TikTok’s scanning policies, the following fields must be included per track:
Monetize
– Allow monetized UGC usageBlockAccess
– Prevent UGC use entirelyTracks without updates after the deadline will be excluded from scanning and monetization
/content/release/save
/content/release/retail/save
2025-03-31
Tiktok Deadline for the new Scanning service (TTS) API documentation Release Notes have been updated and renamed to Changelog.
Deezer is enforcing new contributor metadata requirements starting Q2 2025. Tracks missing required roles will be removed, along with associated albums.
/distribution/release/multiresendtostore
/distribution/release/addtoqueue
/distribution/release/approve
2025-04-14
Global compliance deadline 2025-05-31
Brazil (BR country code) compliance deadline A profileId of 0
, null
, or an absent entry in the artistExternalIds
array will now be treated the same. The
specific behavior of this empty state will differ depending on the store.
Any endpoints responding with an Artist Object will have its artistExternalIds
array contain only existing external
IDs. Values that were previously had "profileId": 0
will no longer appear in the array.
/artists
/artists/summary
/artists/{artistId}
/content/release/save
/content/release/all
/content/release/{releaseId}
2025-03-11
Added support for additional DSPs when it comes to providing Artist External IDs.
/artists
/artists/summary
/artists/{artistId}
/content/release/save
/content/release/all
/content/release/{releaseId}
We no longer support testing on the staging environment. All of the examples and documentation were updated to reflect this change.
Please contact us to create a dedicated Sandbox account.
2025-02-05
We are removing support for redirecting to, and generally using, the outdated V1 Web Interface.
2025-02-05
From this point forward the only supported url will be api.revelator.com
This is currently not a breaking change, but we recommend updating your code to use the primary url, as others might become deprecated in the future.
2025-02-05
Added support for Engagement Analytics to the V3 Analytics. 📊
engagement
metric/analytics/{metric}/{aggregation}
Dolby atmos is officially supported and ready to be distributed.
To supported this change, the Track Object has been updated. Explore the new changes directly on the Track Object and refer to the New track recording model section for more information.
Make sure you understand the limitations and cost associated with Dolby Atmos recordings before creating tracks. Read our Dolby Atmos Guide for more information.
/content/release/save
/content/release/all
/content/release/all/summary
/content/release/{releaseId}
As part of our security hygiene and access protocol work, we’ve moved to a more secure token protocol and updated the related documentation accordingly.
The access token can only be provided in the Authorization header, and must be prefixed with the word “Bearer”. (Bearer token)
2024-08-05
Added this previously undocumented field to the Artist Object.
/content/release/save
/content/release/all
/content/release/{releaseId}
/artists
/artists/summary
/artists/{artistId}
Newly documented Takedowns section.
Added the Common Resources section in order to provide easy-access and overview of this type of data.
New Monetization Policy changes introduced to reflect TikTok’s Monetization Changes
NoTikTokScanning
, Monetize
, BlockAccess
)trackMonetizationPolicyIds
available during
Setting Distribution Options for track-level policies./content/release/retail/save
New fields/changes introduced to reflect TikTok’s Monetization Changes
trackProperties
is a new and required field on the Track Object.trackType
is now a required field on the Track Object. This field also
accepts a new value: 2
- Cover song/content/release/save
/content/release/all
/content/release/all/summary
/content/release/{releaseId}
/distribution/release/{releaseId}/validate
/distribution/release/addtoqueue
2024-07-15
Implementation deadline Attemnts to distribute to stores containing the isActive == false
will now fail.
/distribution/release/multiresendtostore
/distribution/release/addtoqueue
/distribution/release/approve
2024-05-22
Added the (Beta) API support for user invites.
Composer/Writer details on tracks missing either a valid first and last artist name are no longer allowed for distribution.
/distribution/release/multiresendtostore
/distribution/release/addtoqueue
/distribution/release/approve
2024-05-15
Tracks that are less than 2 seconds long are no longer allowed for distribution. Any attempt at distributing or uploading these tracks will fail.
/distribution/release/multiresendtostore
/distribution/release/addtoqueue
/distribution/release/approve
/media/audio/*
2024-05-15
Added a Glossary page containing most used terms.
Royalty tokens are now supported and documented.
Distribution statuses updated.
/distribution/store/all
2024-03-20
The endpoint examples are now back after the documentation migration.
Tipalti integration added to Revelator. By completing the following flows you will be able to pay your payees using this feature:
CTRL + K
)Using an externalUrl
to associate files with a track/release is no longer recommended! Files referenced like this are
not being downloaded by our system until distribution, leading to unexpected behavior. Use the endpoints mentioned above
for all file uploading needs.
/content/release/save
2023-11-11
Newly documented endpoints for uploading files
POST /media/audio/upload/wav
- Upload a file in wav format to the Revelator serversPOST /media/image/upload
- Upload an image file to the Revelator serversPOST /media/audio/pullexternal/wav
- Pull a file in wav format from an external url to the Revalator serversPOST /account/createnewaccount'
- endpoint is now deprecated. This is done to mitigate confusion for creating new
accounts.
/account/createnewaccount
2023-09-26
Enterprise information endpoints:
GET /enterprise/clients/{id}
- Retrieves basic information about a single enterpriseGET /enterprise/clients/all
- Retrieves basic information about all enterprises associated with the account