Distribution

Distribution Workflow

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.
- Validation errors with a severity of 1 must be resolved before a release can be distributed.
- Validation errors with a severity of 2 indicate a probable issue, but do not prevent distribution.
(Optional) Set distribution options. See Setting Distribution Options.
- By default, releases will be distributed as soon as possible and to all territories.
- This step is mandatory when distributing to YouTube Content ID or Facebook Rights Manager.
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.

Validating Releases

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.

Validation errors with a severity of 1 must be resolved before a release can be distributed.
Validation errors with a 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.

POST `/distribution/release/{releaseId}/validate`

Url Params

Parameter	Description
`releaseId`	The ID of the release to validate. This ID was returned in the `/content/release/save` request which created the release.

Response (success)

No Body

Response (error)

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.errorMessage`	string	A human-readable error message of what went wrong
`validationErrors.severity`	integer	Severity level of the issue

Example

↓

Request

curl -X POST 'http://api.revelator.com/distribution/release/540168/validate' \
     -H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'

Response

[
    {
        "objectId": 540168,
        "objectType": "Release",
        "errorMessage": "Release level: The cover image for this release is missing.",
        "severity": 1,
    },
    {
        "objectId": 540168,
        "objectType": "Release",
        "errorMessage": "Release level: The release must include at least one track.",
        "severity": 1,
    }
]

Setting Distribution Options

Use the /content/release/retail/save resource to set distribution options for a release, such as specifying a date the release should go live.

You cannot change distribution options for a release that is currently in distribution queue.

POST `/content/release/retail/save`

Request Body

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 ISO format `YYYY-MM-DD`. When omitted, the release will be live as soon as possible. When provided without `saleStartTime` and `saleStartTimezone`, the release will be live on the `saleStartDate` at midnight in every time zone.
`saleStartTime` optional	string	The time the release should go live, in the format “hh:mm”. When provided, `saleStartDate` is mandatory. When provided without `saleStartTimezone`, the release will go live on the `saleStartDate` at the `saleStartTime` in every time zone. When provided with `saleStartTimzone`, specifies the absolute time that the release should go live. For example, specifying the release should go live at 2pm in Los Angeles will cause it to go live at 5pm in New York.
`saleStartTimezoneId` optional	integer	The timezone for the `saleStartTime`. The release will go live at the same instant everywhere. When provided, `saleStartTime` is mandatory. Mutually exclusive with `saleStartTimezone`. Only provide one or none of these two parameters. Value should be a valid `timezoneId`. To lookup timezones, use the GET /common/lookup/timezoneIds resource.
`saleStartTimezone` optional	integer	The timezone offset for the `saleStartTime`. The release will go live at the same instant everywhere. When provided, `saleStartTime` is mandatory. Mutually exclusive with `saleStartTimezoneId`. Only provide one or none of these two parameters. Value should be a signed integer indicating an offset from UTC+0. Unless this behavior specifically needed, we recommend using `saleStartTimezoneId` instead.
`salePreOrderDate` optional	string	The date the preorder should become available, in the ISO format `YYYY-MM-DD` When provided, `saleStartDate` is mandatory. Must be an earlier date than the `saleStartDate`
`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
`countriesIncluded` optional	array of objects	A list of Country objects (`countryId` only) defining the countries where the release will be distributed. If omitted, the release will be distributed to all available countries.
`countriesIncluded.countryId` required	integer	The Country ID to include.
`countriesExcluded` optional	array of objects	A list of Country objects (`countryId` only) defining the countries where the release will not be distributed. Important: If this array is provided and not empty, `countriesIncluded` will be ignored.
`countriesExcluded.countryId` required	integer	The Country ID to exclude.
`priceTierIds` optional	array of integers	An array of `priceTierId` values to apply to the release/tracks for distribution. This specifies the exact price tiers the release/tracks should be available at. Important Notes: Valid `priceTierId` values can be retrieved using the `GET /common/lookup/pricetiers` endpoint. This property is currently only relevant for distribution to Apple, Amazon, and iTunes/Apple Music. In response, this field will always return `null`, even if values were successfully set. The values are saved properly.

Example

↓

Request

curl -X POST 'http://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
          }
      ],
      "countriesExcluded": [
          {
              "countryId": 881
          },
          {
              "countryId": 224
          }
      ]
 }'

Monetization Policies

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:

Adding the policy to the monetizationPolicyIds on a release level (recommended)
Adding the same policy for all tracks to the trackMonetizationPolicyIds on a track level

If a different policy applies to different tracks in a release (currently only supported for TikTok):

You must use the trackMonetizationPolicyIds on a track level and omit any policyId for that store from the monetizationPolicyIds on a release level

Examples of setting monetization policies

↓

Facebook Rights Manager and YouTube Content ID policies being set at the release level, and different TikTok policies for each track:

"monetizationPolicyIds": [ 332,333 ],
"trackMonetizationPolicyIds": [
    {
        "trackId": 98765,
        "policyId": 334
    },
    {
        "trackId": 98766,
        "policyId": 335
    }
]

Facebook Rights Manager, YouTube Content ID and TikTok policies being set only at the release level (thus applying the TikTok policy to both trackId 98765 & 98766)

"monetizationPolicyIds": [ 332,333,335 ],
"trackMonetizationPolicyIds": []

Monetization policy limitations

Youtube CID and Facebook Rights manager must have the same monetization policies on all tracks in a release.
TikTok allows different monetization policies between tracks in a release.

Monetization Policy Descriptions

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

Adding Releases to the Distribution Queue

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.

POST `/distribution/release/addtoqueue`

Query Params

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.

Request Body

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.

Example

↓

Request

curl -X POST 'http://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]'

Inspecting and Approving Releases

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.

Log in to your parent account.
In the main menu, select Distribution, and then the Inspection sub menu.

The Inspection page appears
The release’s inspection page appears, displaying all the metadata.
Review the metadata for style guide compliance and potential fraud. Pay attention to metadata and ACR cloud warnings and errors.
After checking and editing the metadata as needed, do one of the following:
- Send the release to its destination by selecting Actions then Save and Deliver.
- Return the release to your client by selecting Actions then Fail and Return.

Retrieving Distribution Status

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.

GET `/distribution/store/all`

Query Params

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.

Response

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.

Distribution statuses

The statuses below are ordered by their general progression through the distribution and takedown workflow.

Negative statuses (-13, -11, -10) represent pre-distribution states, such as rejections or pending internal approvals.
Status 0 marks the initiation of the active distribution process.
Higher numbers generally indicate later stages, with specific values representing key milestones or error states. Please note that status numbers do not always increment strictly sequentially across all stages.

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 the 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	Ready for Distribution (Start state for Distribution).
4	Waiting for Download Assets	WaitingForDownloadAssets	Waiting to download files.
5	Downloading Assets	DownloadAssets	Downloading files.
6	Downloading of Assets Failed	DownloadAssetsFailed	Downloading a file failed.
8	Waiting for Audio Encoding	PendingTransformation	Waiting for audio encoding.
10	Encoding Audio	TransformationInProgress	Encoding audio.
11	Encoding Audio Failed	TransformationFailed	Encoding audio failed. Re-queueing the release may fix the problem; if not, please contact customer support.
20	Waiting for 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. These validation issues must be fixed by editing the release and re-adding it to the distribution queue. In order to edit parameters that cannot be edited for locked releases, you must unlock, edit, relock, and then add to queue. For more information about which fields can and cannot be edited for locked releases, see Updating Distributed Releases. If validation failed because of a missing UPC/ISRC and the release’s metadata indicates that Revelator should generate the UPC/ISRC, please contact customer support. Sometimes YouTube will indicate an error that does not require a fix; it is simply a warning/alert.
30	Waiting for Package Creation	WaitingForPackageCreation	Waiting for package creation.
31	Creating Package	CreatingPackage	Creating the package.
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. ”The process cannot access the file” - Error will self-resolve in 24 hours or less. ”Sequence contains no matching element” - Typically an error when the DSP is YouTube CID (307) or Facebook RM (310), and it means that a monetization policy is missing for at least 1 track. ”Object reference not set to an instance of an object” - There are many causes for this error; in general, it indicates that one of the expected references is missing, like the Artist ID for one of the contributors.
45	Triage Pending	WaitingForRevelatorNetcoreDistributionDelivery	Triage Pending.
46	Triage in Progress	WaitingForIdentificationByNetcore	Triage in Progress.
40	Waiting for Upload	WaitingForUpload	Waiting for upload.
41	Uploading Package	Uploading	Uploading the package.
42	Package Upload Failed	UploadingFailed	Uploading the package failed. Re-queueing the release may fix the problem; if not, please contact customer support.
50	Delivered to DSP	Delivered	Uploaded/delivered to the DSP.
60	On Store	OnStore	DSP has provided a link. Confirmed as available on the DSP. Currently, only 4 DSPs support an update to this status. The rest will remain in status `50`.
70	Takedown Pending	TakedownWaitingForPackageCreation	Takedown pending.
71	Takedown Package Creation in Progress	TakedownCreatingPackage	Takedown package creation in progress.
75	Waiting for Enqueue	TakedownWaitingForRevelatorNetcore	Waiting for enqueue.
76	Takedown Enqueued	TakedownEnqueuedByRevelatorNetcore	Takedown enqueued. Waiting for upload.
72	Takedown Uploading	TakedownUploading	Takedown upload in progress.
77	Takedown Failed	TakedownError	Taking down the release failed. Re-queueing the takedown may fix the problem; if not, please contact customer support.
78	Takedown Delivered	TakedownCompleted	Takedown delivered.
79	Removed from Store	RemovedFromStore	Takedown confirmed by DSP.
100	System Error	ProcessError	Processing error.

Example

↓

Request

curl -X GET 'http://api.revelator.com/distribution/store/all?releaseId=540650' \
     -H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
     -H 'Accept: application/json'

Response

{
    "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 }

Updating Distributed Releases

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:

Track count, order and ISRCs are the same.
No audio changes other than those that correct an error (such as blank space, static, or corruption) and do not significantly change track length.
Same UPC
All of the rules and validations from Adding/Editing Releases remain respected.

If any of the above need to be changed, you must issue a takedown for the release and create the release as new.

Updating a release

Edit the release. See Adding/Editing Releases.
Resend the release to the store(s). See Adding Releases to the Distribution Queue.

Takedowns

POST `/distribution/release/takedown`

Takedown a release from one or more stores.

Query Params

Parameter	Type	Description
`releaseId` required	integer	The ID of the release to takedown.

Request Body


An array of Revelator store IDs to takedown. Look up DSP IDs using GET `/common/lookup/stores` (with an access token)

Catalog Management

Analytics

Distribution

Distribution Workflow

Validating Releases

POST /distribution/release/{releaseId}/validate

Url Params

Response (success)

Response (error)

Request

Response

Setting Distribution Options

POST /content/release/retail/save

Request Body

Request

Monetization Policies

Monetization Policy Descriptions

Adding Releases to the Distribution Queue

POST /distribution/release/addtoqueue

Query Params

Request Body

Request

Inspecting and Approving Releases

Retrieving Distribution Status

GET /distribution/store/all

Query Params

Response

Distribution statuses

Request

Response

Updating Distributed Releases

Updating a release

Takedowns

POST /distribution/release/takedown

Query Params

Request Body

POST `/distribution/release/{releaseId}/validate`

POST `/content/release/retail/save`

POST `/distribution/release/addtoqueue`

GET `/distribution/store/all`

POST `/distribution/release/takedown`