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 accurate and acceptable release metadata. Failing to correct inappropriate metadata may cause stores to reject your releases and can ultimately result in the 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 by the `/content/release/save` request which created the release.

Response (success)

This request returns no body when the validation completes successfully.

Response (error)

Parameter	Type	Description
`validationErrors`	array of objects	A list of all validation errors detected for the release.
`validationErrors.objectId`	integer	The ID of the object that caused the error.
`validationErrors.objectType`	string	The type of the object (e.g., `Release`).
`validationErrors.errorMessage`	string	A human-readable message describing the issue.
`validationErrors.severity`	integer	The severity level of the issue (`1` or `2`).

Example

↓

Request

curl -X POST 'http://api.revelator.com/distribution/release/540168/validate' \
     -H 'Authorization: Bearer 00000000-0000-0000-0000-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 DSPs (stores) a release should be distributed to and add it to the distribution queue.

Monetization Policies

In addition to standard distribution, Revelator supports monetization policies for your assets on platforms such as YouTube Content ID and Facebook Rights Manager. These policies determine how your content behaves when used by others - for example, whether it;s tracked, blocked, or monetized.

Before distributing to YouTube Content ID, Facebook Rights Manager or TikTok, you must configure an appropriate monetization policy for each DSP. See Setting Distribution Options.

To enable support for these platforms, please contact your Revelator account manager.

When distributing a release to YouTube Content ID, you must also distribute it 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.
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

Provide an array of Revelator store (DSP) IDs representing where the release should be distributed.

Look up valid DSP IDs using the GET /common/lookup/stores resource. Only DSPs that are enabled for your account will appear in the lookup results.

If you provide a DSP ID that is not enabled for your account or does not exist, the system will return the following error:
"Sequence contains no matching element"

This usually means the provided DSP ID is invalid for your tenant. Always confirm the IDs using the lookup endpoint before submitting the request.

Requests containing distribution stores with isActive == false will fail.
If you distribute to YouTube Content ID (307), Facebook Rights Manager (310) or TikTok (319), ensure monetization policies are already configured.
If you include 307 (YouTube Content ID) in the request body, you must also include 13 (YouTube Music).

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.

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.

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 GET /distribution/store/all endpoint to retrieve distribution statuses across DSPs (stores).

This resource’s behavior changes based on whether you include the releaseId and/or status parameters.

Behavior Overview

No releaseId and no status provided - Returns only counts of releases per store, grouped by store ID. Useful for overall monitoring or dashboard summaries.
status provided, but no releaseId - Returns counts of releases per store in that specific status. For example, you can quickly see how many releases are currently “Delivered” (status = 50) for each DSP.
releaseId provided - Returns detailed statuses for that specific release across all relevant DSPs. This is the only mode that includes individual store-level status data for the release.

To list all releases currently in a given distribution status, use the distributionStatus filter with the GET /content/release/all endpoint.

If a distribution status indicates an error, first review the returned message and attempt to resolve the issue using the provided details. Some errors may resolve automatically after internal retries, while others may require metadata corrections and redistribution.

If the issue persists, please contact Revelator support and include your releaseId(s) or UPC(s) for investigation.

GET `/distribution/store/all`

Query Params

Parameter	Description
`releaseId` optional	The ID of the release to retrieve detailed distribution information for. If omitted, only count data per store will be returned.
`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 the distribution record for a single release-store pair when releaseId is provided.

releaseId - The ID of the release.
distributorStoreId - The DSP (store) identifier.
releaseStatus.status and releaseStatus.statusText - Numeric and textual indicators of the current status.

When calling this endpoint without releaseId, the response will always be aggregated counts per store, optionally filtered by status. To retrieve actual lists of releases in a specific status (for example, all releases currently marked as 50 — Delivered), use the distributionStatus filter on GET /content/release/all.

Distribution statuses

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

Negative statuses (-13, -11, -10, -21, -20) 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).
-21	Failed Owner Inspection	RejectedDealInspection	The final quality inspection by the Revelator failed. The release is returned to the parent account’s inspection queue, where the inspector must review the failure reason and take the appropriate corrective action (edit, reject). Important Note: This status is only relevant for releases distributed using Revelator deal.
-20	Pending Owner Inspection	PendingDealInspection	This status indicates the release is pending final quality inspection by the Revelator. This inspection is triggered when specific conditions are met (e.g., artist matches a deny list, audio matches ACR results). From a child account perspective, this release is still considered Pending Approval (`-10`). Important Note: This status is only relevant for releases distributed using Revelator deal.
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

Monetization Policies

POST /distribution/release/addtoqueue

Query Params

Request Body

Request

Inspecting and Approving Releases

Retrieving Distribution Status

Behavior Overview

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`