Complete the following workflow to distribute a release.
Revelator’s distribution services include both supply chain and agreements with the stores (DSPs). If you would like to use your own distribution agreements for some or all of the stores you distribute to, you must configure this in your parent account.
Validate the release’s metadata. See Validating Releases.
Fix any validation errors by editing the release. See Adding/Editing Releases.
severity
of 1 must be resolved before a release can be distributed.severity
of 2 indicate a probable issue, but do not prevent distribution.(Optional) Set distribution options. See Setting Distribution Options.
Add the release to the distribution queue. See Adding Releases to the Distribution Queue.
Inspect and approve the release’s metadata. See Inspecting and Approving Releases.
Performed in the revelator user interface.
(Optional) Retrieve a release’s distribution status. See Retrieving Distribution Status.
Use the validate
resource to run an automated validation of a release’s metadata. The validation process checks a release for various errors, some of which indicate there may be a problem and others which must be corrected before distribution can proceed.
severity
of 1 must be resolved before a release can be distributed.severity
of 2 indicate a probable issue, but do not prevent distribution.You are responsible for providing acceptable release metadata. Failing to correct inappropriate metadata will result in stores rejecting your releases and will ultimately result in a suspension of your distribution privileges.
/distribution/release/{releaseId}/validate
Parameter | Description |
---|---|
releaseId | The ID of the release to validate. This ID was returned in the /content/release/save request which created the release. |
Parameter | Description |
---|---|
token optional* | Access token returned upon authentication. *Providing a token is mandatory, but alternatively, it can be provided as a header. See Authentication and Headers. |
No Body |
---|
Parameter | Type | Description |
---|---|---|
validationErrors | array of objects | An array of all validation erros on the requested object |
validationErrors.objectId | integer | Id of the Object |
validationErrors.objectType | string | Type of the object eg. Release |
validationErrors.field | string | Which field the validation failed on |
validationErrors.value | any | Value of the field |
validationErrors.errorCode | integer | An error code of the error |
validationErrors.errorMessage | string | A human-readable error message of what went wrong |
validationErrors.severity | integer | Severity level of the issue |
curl -X POST 'http://staging-api.revelator.com/distribution/release/540168/validate' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'
[
{
"objectId": 540168,
"objectType": "Release",
"field": "PosterImage",
"errorMessage": "Release level: The cover image for this release is missing.",
"value": null,
"severity": 1,
"errorCode": 11051
},
{
"objectId": 540168,
"objectType": "Release",
"field": "Tracks",
"errorMessage": "Release level: The release must include at least one track.",
"value": null,
"severity": 1,
"errorCode": 11081
}
]
Use the /content/release/retail/save
resource to set distribution options for a release, such as specifying a date the release should go live.
/content/release/retail/save
Parameter | Type | Description |
---|---|---|
releaseId required | integer | The ID of the release to set distribution options for. This ID was returned in the /content/release/save request which created the release. |
saleStartDate optional | string | The date the release should go live, in the format “mm/dd/yyyy”.
|
saleStartTime optional | string | The time the release should go live, in the format “hh:mm”.
|
saleStartTimezoneId optional | integer | The timezone for the saleStartTime . The release will go live at the same instant everywhere.
|
saleStartTimezone optional | integer | The timezone offset for the saleStartTime . The release will go live at the same instant everywhere.
saleStartTimezoneId instead. |
salePreOrderDate optional | string | The date the preorder should become available, in the format “mm/dd’yyyy”
|
monetizationPolicyIds required | array of integers | Release-level monetization policy ID(s) for YouTube Content ID, Facebook Rights Manager and TikTok. Array should include only one policy for each store, or none if you are not distributing to that store. See Monetization Policies for more information and limitations. |
trackMonetizationPolicyIds optional | array of objects | Track-level monetization policy ID(s) for YouTube Content ID, Facebook Rights Manager and TikTok. Array should include only one policy for each store, or none if you are not distributing to that store. Only TikTok currently supports differing policies per track; for YouTube Content ID and Facebook Rights Manager the policy must be the same for all tracks. See Monetization Policies for more information and limitations. |
trackMonetizationPolicyIds.trackId required | integer | Track ID |
trackMonetizationPolicyIds.policyId required | integer | Policy ID |
curl -X POST 'http://staging-api.revelator.com/content/release/retail/save'\
-H 'Content-Type: application/json'\
-H 'Accept: application/json'\
-d '{ "releaseId": 123456,
"salePreOrderDate": "11/11/2020"
"saleStartDate": "12/11/2020",
"saleStartTime": "05:00",
"saleStartTimezone": 2,
"monetizationPolicyIds": [ 333,332 ],
"trackMonetizationPolicyIds": [
{
"trackId": 98765,
"policyId": 334
},
{
"trackId": 98766,
"policyId": 335
}
]
}'
Monetization policies are used to instruct DSPs with user generated content (UGC) what to do in the event that part, or whole, of your sound recording is used in content (a video, a post, etc.) on their network.
Monetization Policy IDs are unique to each account. Once monetization is enabled for your account, you can retrieve your monetization policy IDs by calling /common/lookup/MonetizationPolicies
(with an access token).
In addition to setting the monetization policy for a store during Setting Distribution Options, you must include the same store in the addtoqueue
request. See Adding Releases to the Distribution Queue.
If the same policy applies to all tracks in a release, you can achieve the same result by:
monetizationPolicyIds
on a release level (recommended)trackMonetizationPolicyIds
on a track levelIf a different policy applies to different tracks in a release (currently only supported for TikTok):
trackMonetizationPolicyIds
on a track level and omit any policyId for that store from the monetizationPolicyIds
on a release levelMonetization policy limitations
You can use these descriptions to better understand the monetization policies available to you.
Policy Name | Relevant Store | Description |
---|---|---|
Monetize in all countries | YT CID (307) | Receive royalties when tracks are used/played |
Track in all countries | YT CID (307) | Receive analytics for when tracks are used/played |
Custom Policy | YT CID (307) | Please contact support to discuss |
Claim Ad earnings | FRM (310) | Receive royalties when tracks are used/played |
Block | FRM (310) | Prevent videos with your tracks from being used/played. |
Monitor | FRM (310) | Receive analytics for when tracks are used/played |
NoTikTokScanning | TT (319) | Provide your sound recording to TikTok’s audio library for inclusion in videos, but do not enable scanning for videos in which it is embedded Use this when your track does not meet the suitability requirements |
Monetize | TT (319) | Scan for videos where your sound recording is being used and generate royalties from these claims |
BlockAccess | TT (319) | Scan for videos where your sound recording is being used and block them |
Use the addtoqueue
resource to specify which stores to distribute a release to and add the release to the distribution queue.
Monetization Policies: In addition to simple distribution, Revelator provides the option to enforce monetization policies for your assets (such as tracking , blocking or claiming earnings) when they are used by others on YouTube (YouTube Content ID) or Facebook (Facebook Rights Manager).
In order to distribute to YouTube Content ID or Facebook Rights Manager, you must first specify a monetization policy for the relevant store. See Setting Distribution Options.
In order to enable this support, please contact your Revelator account manager.
When distributing a release to YouTube Content ID, you must always distribute the release to YouTube Music. Failing to do so will result in a suspension of your YouTube distribution privileges. Additionally, any takedown requests for YouTube Music must also specify YouTube Content ID. There can never be a situation where a release is distributed to YouTube Content ID when it is not distributed to YouTube Music; furthermore, YouTube Content ID cannot have fewer territorial rights than YouTube Music.
It is acceptable to distribute to YouTube Music without distributing to YouTube Content ID.
/distribution/release/addtoqueue
Parameter | Description |
---|---|
releaseId required | The ID of the release to add to the queue. This ID was returned in the /content/release/save request which created the release. |
An array of Revelator store IDs to distribute the release to,
Look up DSP IDs using the GET /common/lookup/stores
resource. Provide an access token to retrieve only the DSPs enabled for a specific account.
Requests containing distribution stores with isActive == false
will fail.
If you are distributing to YouTube Content ID (307) and/or Facebook Rights Manager (310), please ensure that you have already set monetization policies. See Setting Distribution Options.
If you are distributing to YouTube Content ID (307), please ensure you are also distributing to YouTube Music (13). In other words, if the request body array includes ID 307, it must also include ID 13.
curl -X POST 'http://staging-api.revelator.com/distribution/release/addtoqueue?releaseId=540168' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
-H 'Content-Type: application/json' \
-d '[1, 9, 208, 315, 14, 312, 37, 13]'
Releases in the distribution queue will not be sent to stores until a user of your parent account inspects and approves the releases in the Revelator web interface. This involves identifying fraudulent content and metadata style guide violations and preventing releases with these issues from being distributed.
You are responsible for providing acceptable release metadata. Failing to correct inappropriate metadata will result in stores rejecting your releases and will ultimately result in the suspension of your distribution privileges.
Use the distribution/store/all
resource to get the distribution status for a release.
If the distribution status indicates an error has occurred, please attempt to resolve the error with the information below. This may involve simply waiting for an error to resolve itself or editing metadata and redistributing. Please contact customer support with your releaseId(s) for additional assistance.
/distribution/store/all
Parameter | Description |
---|---|
releaseId optional | The ID of the release for which to get distribution information. This ID was returned in the /content/release/save request which created the release. Including this parameter narrows the response to only this release. |
status optional | The status of the releases for which to get distribution information. Please see the Query String Text in Distribution Statuses. Including this parameter narrows the response to only this status. |
Each object in the items
array represents a release being sent to a specific store. The releaseId
indicates the release and the distributorStoreId
indicates the store (DSP). The status
and statusText
parameters in the releaseStatus
object indicate the status.
Status | Status Text | Query String Text | Additonal Information |
---|---|---|---|
-13 | Rejected by Inspector | RejectedByInspector | Metadata for the release was rejected (in parent account) |
-11 | Parked/Hidden | Hidden | Release hidden from metadata inspection queue (put aside to inspect later) |
-10 | Pending Approval | PendingApproval | Pending metadata inspection (Before distribution is approved in the parent account) |
0 | Pending | Pending | Initiating distribution (Immediately after metadata approval in the parent account) |
4 | Waiting for download assets | WaitingForDownloadAssets | Waiting to download files hosted at external URLs from the cloud |
5 | Downloading external assets | DownloadAssets | Downloading files from the cloud |
6 | Downloading external assets failed | DownloadAssetsFailed | Downloading a file failed. Please verify the provided external URL is public and triggers a download of the file (server hosting the file must return a content-disposition header set to “attachment”) |
8 | Pending Transformation | PendingTransformation | |
10 | Transformation In Progress | TransformationFailed | |
11 | Transformation Failed | Transformation failed | Encoding audio failed. Re-queueing the release may fix the problem; if not, please contact customer support. |
20 | Ready for release validation | WaitingForValidation | Waiting for metadata validation |
21 | Validation failed | ValidationFailed | Release has failed the DSP’s unique metadata validation; see the errorMessage for more information.
|
30 | Ready for package creation | WaitingForPackageCreation | Waiting for package creation |
31 | Creating package | CreatingPackage | |
32 | Package creation failed | CreatingPackageFailed | The majority of the time, this indicates a temporary error that will resolve itself; this is due to the system optimizing for speed of delivery vs. 100% delivery on the first try. See the errorMessage for more information.
|
40 | Ready for upload | WaitingForUpload | Waiting for upload |
41 | Uploading package | Uploading | |
42 | Package upload failed | UploadingFailed | Uploading the package failed. Re-queueing the release may fix the problem; if not, please contact customer support. |
50 | Pending Approval | Delivered | Uploaded/delivered to the DSP |
60 | On store | OnStore | Confirmed as available on the DSP |
70 | Waiting for Takedown | WaitingForRemove | |
71 | Removing from store | Removing | Removing from DSP |
72 | Takedown Uploading | TakedownUploading | |
75 | Takedown Waiting to process | TakedownWaitingForRevelatorNetcore | |
76 | Takedown enqued | TakedownEnqueuedByRevelatorNetcore | |
77 | Removing failed | RemovingFailed | Taking down the release failed. Re-queueing the takedown may fix the problem; if not, please contact customer support. |
78 | Takedown request delivered | RemoveDelivered | |
79 | Takedown processed | TakedownProcessed | Takedown confirmed by DSP |
100 | Error in process, please try again. | ProcessError | Processing error |
curl -X GET 'http://staging-api.revelator.com/distribution/store/all?releaseId=540650' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
-H 'Accept: application/json'
{
"totalItemsCount": 3,
"pageNumber": 1,
"pageSize": 3,
"items": [
{
"releaseId": 0,
"distributorStoreId": 1,
"albumsCount": 0,
"singlesCount": 0,
"epCount": 0,
"ringtonesCount": 0,
"videosCount": 0,
"totalQuantity": 0,
"totalNet": 0.0,
"releasePriceId": null,
"trackPriceId": null,
"releaseStatus": {
"status": -10,
"statusText": "Pending Approval",
"errorMessage": null,
"addedDate": "2019-12-19T09:15:56.15",
"deliveryDate": null,
"dateLive": null,
"urlInStore": null,
"summarySection": 5,
"isError": false
},
"inProgressCount": 0,
"inspectionCount": 0,
"licensingCount": 0,
"deliveredCount": 0,
"mayBeLiveCount": 0,
"liveCount": 0,
"errorCount": 0
},
{
"releaseId": 0,
"distributorStoreId": 6,
"albumsCount": 0,
"singlesCount": 0,
"epCount": 0,
"ringtonesCount": 0,
"videosCount": 0,
"totalQuantity": 0,
"totalNet": 0.0,
"releasePriceId": null,
"trackPriceId": null,
"releaseStatus": {
"status": -10,
"statusText": "Pending Approval",
"errorMessage": null,
"addedDate": "2019-12-19T09:16:05.417",
"deliveryDate": null,
"dateLive": null,
"urlInStore": null,
"summarySection": 5,
"isError": false
},
"inProgressCount": 0,
"inspectionCount": 0,
"licensingCount": 0,
"deliveredCount": 0,
"mayBeLiveCount": 0,
"liveCount": 0,
"errorCount": 0
},
{
"releaseId": 0,
"distributorStoreId": 315,
"albumsCount": 0,
"singlesCount": 0,
"epCount": 0,
"ringtonesCount": 0,
"videosCount": 0,
"totalQuantity": 0,
"totalNet": 0.0,
"releasePriceId": null,
"trackPriceId": null,
"releaseStatus": {
"status": -10,
"statusText": "Pending Approval",
"errorMessage": null,
"addedDate": "2019-12-19T09:15:56.413",
"deliveryDate": null,
"dateLive": null,
"urlInStore": null,
"summarySection": 5,
"isError": false
},
"inProgressCount": 0,
"inspectionCount": 0,
"licensingCount": 0,
"deliveredCount": 0,
"mayBeLiveCount": 0,
"liveCount": 0,
"errorCount": 0
}
],
"аdditionalCounters": null }
In many cases, it is possible to update a release without a full takedown. Stores do not require a full takedown as long as the following are all true:
If any of the above need to be changed, you must issue a takedown for the release and create the release as new.
/distribution/release/takedown
Takedown a release from one or more stores.
Parameter | Type | Description |
---|---|---|
releaseId required | integer | The ID of the release to takedown. |
An array of Revelator store IDs to takedown. Look up DSP IDs using GET /common/lookup/stores (with an access token) |