Distribution

Distribution Workflow

Complete the following workflow to distribute a release.

1. Validate the release’s metadata. See Validating Releases.

2. 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.

3. (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.

4. Add the release to the distribution queue. See Adding Releases to the Distribution Queue.

5. Inspect and approve the release’s metadata. See Inspecting and Approving Releases.

   Performed in the revelator user interface.

6. (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.

POST /distribution/release/{releaseId}/validate

Url Params

Query Params

Response (success)

Response (error)

Example

Request

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

Response

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

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.

POST /content/release/retail/save

Request Body

Example

Request

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

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).

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

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

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

Monetization Policy Descriptions

You can use these descriptions to better understand the monetization policies available to you.

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.

POST /distribution/release/addtoqueue

Query Params

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.

Example

Request

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]'

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.

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

3. The Inspection page appears
4. The release’s inspection page appears, displaying all the metadata.
5. Review the metadata for style guide compliance and potential fraud. Pay attention to metadata and ACR cloud warnings and errors.
6. 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.

GET /distribution/store/all

Query Params

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

Example

Request

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'

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.

Updating a release

1. Edit the release. See Adding/Editing Releases.
2. 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

Request Body