Getting Started

Introduction

The Revelator API enables partners to provide Revelator functionality to artists or other collaborators directly from their own applications.

All API partners are given an API key that is required to access certain key endpoints. The API key is effectively a "client secret".

Warning

Make sure that your API key never goes into client side code; otherwise, your clients will be able to abuse it!

Tip

The Revelator API powers the Revelator web interface. Because the external API offering is also used internally, developer’s can view API requests initiated by the web interface and use these requests as working samples. Additionally, they can view (and validate) the results of their API requests in the web interface.

Base URLs

Use the staging environment for all testing. Note that all accounts and content in staging are periodically overwritten with the accounts and content in production.

Table 1. API URLs

Production

https://app-api.revelator.com

Staging

https://staging-api.revelator.com



Table 2. Revelator Web Interface URLs

Production

https://app.revelator.com

Staging

https://staging.revelator.com



Note

The above web interface URLs are generic. To access the production environment's web interface with your white label's custom branding, use your white label's custom URL.

Authentication and Headers

Note

Some endpoints in the API are not performed as users and therefore do not require access tokens. For example, Signing Up New Users. These tasks always require you to provide your API key.

Access Tokens

Retrieve an access token for a user by Authenticating. The access token must be sent with each subsequent request in one of the following ways:

  • As a header "authorization" with the value set to "bearer <token>". (standard bearer token)

  • As a header named "token" with the value set to the token

  • As a query string parameter “token” with the value set to the token:

    <Endpoint_URL>?token=<access token>

Content Type

Unless otherwise specified, the content type for the request body is application/json.

Implementation Models

Revelator is a highly customizable application which is relevant for many use cases.

Child Account Model

For API implementations using the child account model, tasks are performed within a user's personal Revelator account.

  • Partner application will create a new user and child account in the Revelator system for each of the partner's users. All child account assets (releases and tracks) will appear in the partner tenant.

  • Required model for any use case which involves directing your users to the Revelator web interface, such as a White Label.

  • Partner can choose to authenticate their users with or without their knowledge or involvement (prompted or unprompted authentication).

  • Partner will perform administrative tasks, such as inspecting release metadata, in the partner tenant in the Revelator web interface.

    API access is possible for partners building their own administrator application. Please contact support for details.

  • Partners using the Reporting API will additionally perform administrative tasks via the API in their partner tenant, such as managing contracts.

  • Recommended for customers seeking to utilize built-in automation, such as default contracts per child account

Single Tenant Model

For API implementation using the single tenant model, all tasks will be performed in the partner tenant.

Note

Upon onboarding, Revelator will provide you with a partnerUserId, in addition to your API key and Enterprise ID.

  • Partner does not signup each user individually in the Revelator system (does not use the signup resource).

  • Partner will always authenticate in the Revelator system without the users knowledge/involvement ( will always uses unprompted authentication).

  • Partner will perform administrative tasks, such as inspecting release metadata in the Revelator web interface.

    API access is possible for partners building their own administrator application. Please contact support for details.

  • Not recommended for customers seeking to utilize built-in automation, such as default contracts per child account. Alternatively, default contracts may be less useful for partners using the Reporting API as they may require many custom contracts.

Workflow

  1. (For child account implementation model only) Signup up a new user. See Signing Up New Users.

  2. Authenticate. See Authenticating.

  3. Create releases. See Adding/Editing Releases.

    Note

    Defining your catalog in the Revelator system is necessary whether or not you are distributing through Revelator.

Workflows for White Labels

Note

This section is only relevant for White Label customers who are signing up and/or authenticating users via the API and then redirecting to their White Label user interface.

For partners who are not maintaining their own database of user credentials:

To create a custom signup and login page
  1. Implement prompted signup. See Signing Up New Users .

  2. Implement prompted authentication. See Authenticating.

  3. Load the account in the Revelator web interface. See Redirecting Authenticated Users to the Web Interface.

To create a custom signup and login page and maintain the ability to perform unattended API requests

Note

This implementation enables you to retrieve an access token both when your user provides their credentials or on behalf of your user (without user interaction).

  1. Implement prompted signup. See Signing Up New Users .

  2. For the custom login page, implement prompted authentication, and then load the account in the Revelator web interface. See Authenticating. and Redirecting Authenticated Users to the Web Interface.

  3. For unattended API requests, implement unprompted authentication, and then implement the desired Revelator API requests. See Authenticating.

For partners who are maintaining their own database of user credentials:

To direct users to the Revelator application with unattended authentication
  1. Implement unprompted signup. See Signing Up New Users.

  2. Implement unprompted authentication. See Authenticating.

  3. Load the account in the Revelator web interface. See Redirecting Authenticated Users to the Web Interface.

To provide Revelator functionality in a custom application
  1. Implement unprompted signup. See Signing Up New Users.

  2. Implement unprompted authentication. See Authenticating.

  3. Implement the desired Revelator API requests using the access token retrieved with authentication.

Signing Up New Users

Resource Prerequisite: Only relevant for partners whose accounts are enabled for child account creation.

Use the signup resource to create new accounts and users.

Note

This resource is not relevant for partners who chose to execute all their API calls (for all of their users) in their partner tenant.

This resource does the following:

  1. Creates a new child account. This new account is a sub-tenant of the partner's parent tenant; all content in the child is visible in the parent.

  2. Creates a new user for the child account. This user is the owner of the account.

  3. Creates all entities required to manage content and payments for the account: a Rights Holder, Payee, and Contract.

    • The Rights Holder created with the account will be a Label. Additional Artist and Label rights holders can be defined.

      Note

      Every release is associated with rights holders: an artist and a label. When adding a release, you can reference existing rights holders or create new rights holders.

    • The Payee created with the account will be for the user of the account. The default Contract will stipulate that the Payee will receive 100% of the royalties the partner is paying out.

    • The Rights Holder, Payee, and Contract will all be visible in the parent account.

The signup resource allows you to signup users with or their involvement or unattended.

  • Prompted Signup. The partner application prompts users for their information in a custom signup page.

    • Users will have knowledge of their credentials, and can use them to login to the Revelator web interface directly or via a custom login page. (Prompted authentication)

    • Supports prompted authentication, unprompted authentication, and the Revelator web interface's login page. For more information, see Authenticating.

      Tip

      Using prompted and unprompted authentication together would be useful in a case where you don't want to maintain your own user database, but you do want to maintain your ability to perform unattended authentication.

  • Unprompted Signup. The partner application automates signup; the user is not prompted for their information and has no knowledge of anything outside of the partner application.

    • Ideal for API partners creating a complete, standalone application.

    • User and account information is provided by the partner directly, and the user will not have knowledge of their login credentials. The partner may already have all the information about the user stored in their application, or they may need to prompt the user for some information, but the user is not prompted to assign themselves credentials.

    • Supports unprompted authentication. For more information, see Authenticating.

Figure 1. Signup/Authentication Scenarios
Signup/Authentication Scenarios

For more information about authentication, see Authenticating



POST /partner/account/signup

Table 3. Request Body Parameters

Parameter

Type

Description

email

Mandatory

integer

User's email.

  • Must be unique

  • Must be a PayPal email address in order for the partner to pay royalties to the user via Revelator

The partner can pay each user via PayPal or manage payments to users externally. When using Revelator's distribution deals, Revelator will pay the partner according to the payout preferences specified for the parent account.

password

Mandatory

string

User's password (minimum of 6 characters).

For prompted signup: Partners using prompted signup must prompt users for this value.

For unprompted signup: Partners using unprompted signup (and therefore, unprompted authentication) must still provide a value for this parameter. The user will have no knowledge of this value and the partner will have no need for it as it is not required for unprompted authentication.

enterpriseName

Mandatory

string

The name of the artist, manager or label represented by the account.

This will be the name of the Rights Holder, Payee, and Contract automatically created with the account.

firstname

Optional

string

User's first name.

lastname

Optional

string

User's last name.

type

Mandatory

string

Growth - The type of child account to create. Growth is the appropriate account type for all API users.

partnerAPIKey

Mandatory

string

API key provided upon onboarding.

partnerUserId

Optional

string

Unique ID for the user.

The ID is used for unprompted authentication. It is recommended to use the user's existing ID in the partner application, avoiding the need for partners to save additional credential information.

When unprompted authentication will never be used, this parameter is unnecessary and can be omitted.

maxArtists

Optional

integer

Maximum number of artists the user can create in the account. By default, there is no artist limit.

The following count as an artist towards the maximum:

  • Each artist named as the primary artist for a release (contributors, even contributors with the Primary Artist role, do not count)

  • Each compilation release (there is no artist named for the release; there are artists named for each track)

storeAccess

Optional

object

Controls which stores (digital service providers / DSPs) the child account can distribute to. By default, all stores available in the partner's parent account will be available in the child account.

Parameter

Type

Description

type

string

  • all - All stores available in the partner's parent account will be available

  • some - The stores specified in storeIds will be available

  • none - The child account will not be able to distribute releases

storeIds

array of integers

The Revelator ID for each store that will be available,

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.



Table 4. Response

Response Body (success)

Parameter

Type

Description

userId

string

The Revelator user ID for the newly created user.

enterpriseId

integer

The Revelator account ID for the newly created child account.

Store this ID in order to make upgrades to the account in the future.

HTTP codes

Code

Description

204 No Content

Success

403 Forbidden

If the request would grant an account access to resources the partner doesn't have access to. For example, setting storeIds to a store the partner doesn't have access to.



Request
curl -iv -X POST "https://staging-api.revelator.com/partner/account/signup”\
-H "Accept:application/json"\ 
-H "Content-Type:application/json" \
-d ‘{ "email":"exampleemail@company.com",
    "password":"password123",
    "enterpriseName": "John Doe Band",
    "firstname":"John",
    "lastname": "Doe",
    "type":"Launch",
    "partnerApiKey":"00000000-0000-0000-0000-000000000000",
    "partnerUserId":"XXXXX"}’
Response
JSON
{ userId: "a57cbed3-3bf1-4ada-b16c-40d0320bfc8cb",
  enterpriseId: 123456}

Upgrading Accounts

Use the upgrade resource to change attributes of accounts created with the signup resource.

POST /partner/account/upgrade

Table 5. Request Body Parameters

Parameter

Type

Description

partnerAPIKey

Mandatory

string

API key provided by your Revelator account manager.

enterpriseId

Mandatory

integer

The Revelator account ID for the child account you want to upgrade. This ID was returned in the signup request which created the account.

newType

Optional

string

The type of child account. By default, this value will not be updated for the account.

  • Growth is the recommended account type for all API customers.

Note that changing the account type has no impact on existing rights holders; the initial rights holder that was created with the signup request will not be impacted in anyway, and no additional rights holder will be created with this request.

newMaxArtists

Optional

integer

Maximum number of artists the user can create in the account. By default, this value will not be updated for the account. The following count as an artist towards the maximum:

  • Each artist named as the artist for a release (for at least one release)

  • Each compilation release (there is no artist named for the release; there are artists named for each track)

newStoreAccess

Optional

object

Controls which digital service providers (DSPs) the child account can distribute to. By default, this value will not be updated for the account.

Parameter

Type

Description

type

string

  • all - All stores available in the partner's parent account will be available

  • some - The stores specified in storeIds will be available

  • none - The child account will not be able to distribute releases

storeIds

array of integers

The Revelator ID for each store that will be available. Only specify DSPs which are enabled in your parent account.

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.



Table 6. Response

Response Body

None

HTTP codes

Code

Description

204 No Content

Success

403 Forbidden

If the request would grant an account access to resources the partner doesn't have access to. For example, setting storeIds to a store the partner doesn't have access to.

409 Conflict

If the request would prevent an account from using resources it's already using. For example, setting newMaxArtists to 1 for an account that has 5 artists.



Authenticating

The Revelator API provides two authentication resources. Both resources return access tokens when the parameters provided in the requests are valid.

Whether you use one, the other or both depends on your use case.

The login resource allows you to login users with their involvement (prompted). The loginpartner resource allows you to login users unattended (unprompted).

Note

Unprompted login is recommended in most cases. Prompted login is the preferred method only when the partner is not maintaining their own database of user credentials.

  • Prompted Login. The partner application prompts users for their information in a custom login page.

    • The user must have knowledge of their credentials. Signup must occur via a custom signup page (prompted signup) or via the Revelator web interface.

    • Requires a reCAPTCHA integration with the Revelator server. Please contact your account manager. You will need to provide your domain name and they will provide with the public site key.

  • Unprompted Login. The partner application automates login; the user is not prompted for their information and has no knowledge of anything outside of the partner application.

    • The partner application provides the partnerUserId parameter.

      For child accounts: The partnerUserId parameters for your users are set by you (the partner application) when Signing Up New Users. Signup must occur through a prompted or unprompted API implementation, and not via the Revelator web interface.

      For partner tenant: The partnerUserId parameter for the partner tenant is provided to you (the partner) upon onboarding, when relevant. This is relevant for:

      • Partners who are executing all their API calls in the partner tenant (single tenant model) and are not creating sub-accounts for each of their users in the Revelator system.

      • Partners who are executing API calls in their partner tenant in addition to their user's sub accounts. This is relevant for partners managing royalties via the API (API plan C).

Figure 2. Signup/Authentication Scenarios
Signup/Authentication Scenarios

For more information about signup, see Signing Up New Users



POST /account/login

Note

The body of this request must be x-www-form-urlencoded instead of JSON.

Table 7. Request Body Parameters

Parameter

Type

Description

username

Mandatory

string

User's email.

password

Mandatory

string

User's password.

recaptchaToken

Mandatory

string

Token retrieved from recaptcha. For more information, see .



Request
curl --location --request POST 'http://staging-api.revelator.com/account/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=USER@DOMAIN.COM' \
--data-urlencode 'password=PASSWORD' \
--data-urlencode 'recaptchaToken=RECAPTCHA_TOKEN'

POST /partner/account/login

Table 8. Request Body Parameters

Parameter

Type

Description

partnerUserId

Mandatory

string

partnerUserId value assigned to the user in the signup resource. See Signing Up New Users.

partnerApiKey

Mandatory

string

API key provided by your Revelator account manager.The API provided by your account manager.



Request
curl -X POST 'https://staging-api.revelator.com/partner/account/login'\ 
-H 'Content-Type: application/json'\  
-H 'Accept: application/json'\  
-d '{ "partnerUserId": "user123",  
    "partnerApiKey":"00000000-0000-0000-0000-000000000000" }'

Redirecting Authenticated Users to the Web Interface

Note

This section is only relevant for White Label customers who are signing up and/or authenticating users via the API and then redirecting to their White Label user interface.

Once you have prompted the user for their credentials and confirmed the credentials are valid by authenticating the user, you can redirect the user to their account in the Revelator web interface.

To load the user's account, you must provide the access token returned in the /account/login resource in the appropriate URL.

Table 9. URLs to load a user's home page

Production

https://<Custom_Production_URL>/Home/IndexWithToken?serverToken=<access_token>

Staging

https://staging.revelator.com/Home/IndexWithToken?serverToken=<access_token>



Deep Linking. For deep linking, include the query string parameter redirectToRouteOnLoad, and set it equal to the route. For example, to load the assets page: https://staging.revelator.com/Home/IndexWithToken?serverToken=<access_token>&redirectToRouteOnLoad=/content/music/albums

Note

  • Your custom production URL (your white label deployment's custom domain) must be used in order to load the web interface with your white label's customizations. "app.revelator.com" is the generic URL for the Revelator web interface's production environment, and using this URL to load a user's account will result in the standard web interface.

  • If a user has access to more than one Revelator account, the user's default account will be loaded. The user can switch to other accounts using the Switch Account link in the main menu.

Adding and Editing Content

Adding/Editing Releases

A release is an album, EP, or single. Releases contain one or more tracks and various metadata. Use the /content/release/save resource to create or edit releases. Specifically, this resource enables you to do the following:

  • Manage release metadata, including uploading relevant files

  • Create new tracks and assign them to the release

  • Assign existing tracks to a release, with or without editing them

Warning

Unless otherwise stated, the Revelator API does not support partial updates. When editing an object, the existing values of any omitted parameters will be deleted or overwritten, according to the designated behavior for a null value for that parameter. Consequently, we recommend you always query the object you want to edit and modify the JSON object to avoid partial update problems.

POST /content/release/save

Table 10. Query String Parameters

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.



Table 11. Request Body Parameters

Parameter

Type

Description

name

Mandatory

string

Title of the Release.

  • Required for new releases.

  • When provided with an existing releaseId, updates the name of the release.

releaseId

Optional

integer

ID for the existing release you want to edit. This ID was returned in the response when the release was created.

  • When set to 0, creates a new release. (Default)

  • Inline with the general behavior of this API, patching is not supported. Existing values for omitted parameters will be deleted or overwritten.

artistName

Optional

string

Name of the release’s primary artist/band.

  • Should be only the name of one artist.

    • The artist named in this parameter will be the only artist named for the release in contracts and analytics.

    • Additional artists should be named as contributors. If there is more than one primary artist, additional primary artist should be listed as contributors with the role Primary Artist.

  • When provided without an artistId, tries to find an existing artist with the same name (ASCII SQL). If no such artist is found, creates a new artist.

  • When provided with an artistId, the artistName is ignored. The artist associated with the artistId will be assigned to the release and the name of the artist will not be updated.

  • Should be omitted for compilations. Otherwise, either an artistName or artistId must be provided. If neither are provided, the artist will be null, and this is only valid for compilations.

  • All artists in child enterprises automatically appear as Rights Holders in the parent enterprise.

artistId

Optional

integer

ID for an existing artist to assign as the primary artist for the release.

  • Should be omitted for compilations. Otherwise, either an artistName or artistId must be provided. If neither are provided, the artist will be null, and this is only valid for compilations.

releasesLocals

Mandatory

array of objects

Release name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the release name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).

  • Parameter is mandatory even if the array is empty.

  • Each object in the array represents the name in a different language.

  • If name or languageId are omitted, the object will be ignored.

Parameter

Type

Description

name

Mandatory

string

Name in the indicated language.

version

Optional

string

Version in the indicated language.

languageId

Mandatory

integer

Language ID indicating the language of the name. Each language can be used only once in the array.

Lookup up the languageId using the GET /common/lookup/languages resource.

artistLocals

Optional

array of objects

Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).

  • Each object in the array represents the name in a different language

Parameter

Type

Description

name

string

Name in the indicated language.

languageId

integer

Language ID indicating the language of the name. Each language can be used only once in the array.

Lookup up the languageId using the GET /common/lookup/languages resource.

contributors

Mandatory

array of objects

Additional key artists who should be given top level credit. Do not provide individual band member names or supporting musicians.

  • Parameter is mandatory even if the array is empty.

  • Each object in the array represents a contributor.

  • Legacy contributors: Prior to July 2021, contributors were not added as artists. The contributor object included a name parameter and did not include an artist object. The name parameter directly in the contributor object is deprecated, and should never be used for new contributors. When editing an existing release with legacy contributors, we recommend prompting users for the data required by the artist object and providing the contributor object according to the current standard.

Parameter

Type

Description

contributorId

Optional

GUID

ID for an existing contributor.

  • Not relevant for new releases. Should be provided when editing existing releases.

roleId

Mandatory

integer

  • 5 - Featuring

  • 49 - Primary Artist*

  • 34 - Producer

  • 6 - Remixer

  • 7 - With

*Should only be used to name additional primary artists. The first (or only) primary artist should only be indicated with the artistName parameter.

For information about additional roles, use the GET /common/lookup/contributorRoles resource.

Note that it is strongly encouraged to use a reduced set of contributor roles, such as those visible in the Revelator web interface. Many users will be tempted to add extraneous roles which will result in the release being rejected by top tier DSPs. Furthermore, even though publishing roles do exist for this attribute, they should never be used; publishing credits should be provided per track in the composerContentsDTO array.

artist

Mandatory

object

The contributing artist.

Unlike all other artists in Revelator, contributing artists with any role other than Primary Artist, Featuring, or Remixer DO NOT require external artist IDs. In other words, contributing artists with the roles Primary Artist, Featuring, or Remixer require Apple and Spotify IDs (same as primary artists); contributing artists with other roles do not require these IDs (they are optional).

See Artist Object.

version

Optional

string

Title version. For example, Remastered or Deluxe edition.

Typically omitted unless the release is a new version of a previously released release.

copyrightP

Mandatory

string

The product copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc.

The product copyright holder is the person or entity that owns the exclusive rights to the complete product, including both sound recording and artwork.

copyrightC

Mandatory

string

The sound recording copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc.

The sound recording copyright holder is the person or entity that owns the exclusive rights to the sound recording.

hasRecordLabel

Optional

boolean

  • true - The release has a record label.

    See additional required parameters below.

  • false - The release does not have a record label. (Default)

    • If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release.

    • If the primary artist for the release is new or is an existing artist not associated with a label, a new label will be created and assigned to the release with the same name as the artist.

labelName

Optional

string

Name of the label.

  • Should never be provided when hasRecordLabel is false.

  • When provided without labelId, tries to find an existing label with the same name (ASCII SQL). If no such label is found, creates a new label and assigns it to the release.

  • When provided with labelId, the labelName is ignored. The label associated with the labelId will be assigned to the release and the name of the label will not be updated.

  • If neither a labelId nor a labelName are provided and hasRecordLabel is true:

    • If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release.

    • If the primary artist for the release is new or is an existing artist not associated with a label, throws an exception.

labelId

Optional

integer

ID for an existing label to assign to the release.

  • Should never be provided when hasRecordLabel is false.

  • If neither a labelId nor a labelName are provided and hasRecordLabel is true:

    • If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release.

    • If the primary artist for the release is new or is an existing artist not associated with a label, throws an exception.

artistAppleId

Mandatory

integer

One of the following:

  • For artists already on Apple Music, existing Apple ID for the artist.

    To find this ID, go to your Apple Music artist page, and copy-paste the numeric part of the URL. Example 1249595

  • For artists not already on Apple Music, 0.

    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.

artistSpotifyId

Mandatory

integer

One of the following:

  • For artists already on Spotify, existing Spotify ID for the artist.

    To find this ID, go to your Spotify artist page, and copy-paste the numeric part of the URL. Example: 22bE4uQ6baNwSHPVcDxLCe

  • For artists not already on Spotify, 0.

    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.

previouslyReleased

Optional

boolean

  • true - The release has been released previously.

    In this case, upc and releaseDate are required parameters.

  • false - The release has not been released previously. (Default)

upc

Optional

integer

UPC/EAN/JAN code for the release.

  • The UPC is a unique code that every release must have. The system will automatically generate one upon distribution (free of charge) if you omit this parameter. You should never generate a new UPC for a release that already has one.

  • Required when previouslyReleased is true.

releaseDate

Optional

string

Official date the release was previously released in the format "mm/dd/yyyy".

  • Should only be provided when previouslyReleased is true (and in this case, it is required). For releases that have not yet been released, this parameter is automatically set according to the saleStartDate parameter in the distribution options endpoint. See Setting Distribution Options.

primaryMusicStyleId

Mandatory

integer

ID for the release's primary music style.

Lookup music style IDs using the GET /common/lookup/musicstyles resource.

languageId

Mandatory

integer

Language ID for the release’s meta data. This is not the language of the songs/lyrics, but the language of the information provided in this API request.

Lookup up the languageId using the GET /common/lookup/languages resource. English is 1.

tracks

Optional

array of objects

Tracks for the release.

  • Each object in the array represents a track.

  • Unlike the behavior for most parameters, completely omitting the tracks parameter when editing an existing release will not remove all existing tracks from the release.

  • Although tracks are not required when creating a release, they are required to distribute the release.

See Track Object.

image

Optional

object

Cover image for the release.

  • Although a cover image is not required when creating a release, it is required to distribute the release.

  • Stores and services will reject images that do not conform to the following standards:

    • Technical specifications:

      • File format must be PNG, GIF, BMP, TIF, JPG or JPEG

      • Color space must be RGB

      • Minimum dimensions of 1400x1400 pixels; 3000x3000 pixels recommended

      • Must be a square image (width and height the same)

      • May not contain more than 50 megapixels or be larger than 10 Mb

      • Cannot be stretched, upscaled, or appear to be low-resolution

    • Content:

      • Information must match album title and artist name

      • No website addresses, social media links or contact information

      • No sexually explicit imagery

      • Cannot be misleading by figuring a different artist's name more prominently

      • No third-party logo or trademarks without express written permission from the trademark holder

  • In line with the general behavior of this API, patching is not supported. When editing an existing release associated with an existing file, you must include this object (with the existing fileId and fileName) to prevent the file from being deleted.

See File Object.



Request
curl -X POST 'http://staging-api.revelator.com/content/release/save?token=2ec6ba54-3199-473a-a129-296bf672a759'\
--header 'Content-Type: application/json'\ 
--header 'Accept: application/json'\
-d '{ "artistName":"Release_artist",  
      "contributors": [], 
      "copyrightC": "2018 companyC",
      "copyrightP": "2018 companyP", 
      "hasRecordLabel": false,  
      "previouslyReleased": false,  
      "languageId": 1,  
      "name": "Single",  
      "primaryMusicStyleId": 60,   
      "releasesLocals": [], 
      "image": { "externalUrl":"https://www.dropbox.com/s/24ky6wvnu2ksv7f/sourceFileName.jpg?dl=1", 
                 "filename":"file123.jpg" }, 
      "tracks": [ {"artistName": "TRACK_ARTIST", 
                   "languageId": 1, 
                   "name":"Single",  
                   "explicit": false,
                   "trackType": 1,                 
                   "wav": { "filename":"file123.wav", 
                            "externalUrl" :"https://www.dropbox.com/s/3telykbgq2tf3ln/ sourceFileName.wav?dl=1" }, 
                   "trackLength": 267, \ 
                   "sampleRate": 44100, \
                   "composerContentsDTO":[{ "composerName": "John Doe",
                   	                    "rightsId": 1, 
		                            "roleId": 2, 
	                                    "share":100 }]} 
              ] 
     }'

Artist Object

Parameter

Type

Description

name

Optional

string

Name of the artist.

  • When provided without an artistId, tries to find an existing artist with the same name (ASCII SQL). If no such artist is found, creates a new artist.

  • When provided with an artistId, updates the name of the artist.

  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.

  • All artists in child enterprises automatically appear as Rights Holders in the parent enterprise.

artistId

Optional

integer

ID for an existing artist.

  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.

artistExternalIds

Optional*

array of objects

External IDs for the artist.

*Mandatory for all artists, except for contributors with roles other than Primary Artist, Featuring, or Remixer. For all artists where this parameter is mandatory, this array must include an object for every supported store.

  • These IDs are used by the stores to make sure that all of an artist's content stays together. For artists who have not yet distributed to a specific store, we will generate a new ID if/when a release for the artist is distributed to the store.

  • Each object in the array represents an external ID for the artist at a specific store.

Parameter

Type

Description

profileID

Mandatory

integer

One of the following:

  • For an artist already on the store, external ID for the artist at the specified store.

    To find this ID go to the artist's page at the store, and copy-paste the numeric part of the URL

  • For artists not already on the store, 0.

    This indicates we should generate an ID for the artist if/when a release for the artist is distributed to the store.

    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.

distributorStoreId

Mandatory

integer

Revelator ID for the store.

Currently supported for:

  • Apple Music - 1

  • Spotify - 9

artistLocals

Optional

array of objects

Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).

  • Each object in the array represents the name in a different language

Parameter

Type

Description

name

string

Name in the indicated language.

languageId

integer

Language ID indicating the language of the name. Each language can be used only once in the array.

Lookup up the languageId using the GET /common/lookup/languages resource.

File Object

Parameter

Type

Description

filename

Optional

string

Name of the file, including the extension.

externalURL

Optional

string

URL to the hosted file.

  • URL must be publicly available

  • URL must trigger a download of the file (server hosting the file must return a content-disposition header set to “attachment”)

  • The external URL method for uploading a file to the Revelator server enables partners to easily provide files to Revelator that they are hosting for their users. The upload to the Revelator server occurs upon release creation or upon distribution, after which the file no longer needs to be hosted externally.

fileId

Optional

integer

The ID for a file that has already been uploaded to the Revelator server.

Track Object

Parameter

Type

Description

name

Optional

string

Title of the track.

  • Required for new tracks.

  • When provided with an existing trackId, updates the name of the track.

  • Do not include additional information, like “Remix” or “Uncut”. This should be specified in the version.

trackId

Optional

integer

ID for an existing track you want to assign to the release. This ID was returned in the response when the track was created.

Note that you should not use the same trackId on more than one release. You should only provide an existing trackId in a case where you are editing an existing release or assigning a track that is not yet assigned to any release. In a case where the same track (same ISRC) is used on more than one release, you should create the track as new for the second release (generate a new trackId).

  • When set to 0, creates a new track. (Default)

  • In line with the general behavior of this API, patching is not supported. When assigning an existing track to a release, the track will be updated according to the data provided; any existing values for omitted parameters will be deleted.

artistName

Optional

string

Name of the track's primary artist/band.

  • Should be only the name of one artist.

    • The artist named in this parameter will be the only artist named for the release in contracts and analytics.

    • Additional artists should be named as contributors. If there is more than one primary artist, additional primary artist should be listed as contributors with the role Primary Artist.

  • When provided without an artistId, tries to find an existing artist with the same name (ASCII SQL). If no such artist is found, creates a new artist.

  • When provided with an artistId, the artistName is ignored. The artist associated with the artistId will be assigned to the release and the name of the artist will not be updated.

  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.

  • All artists in child enterprises automatically appear as Rights Holders in the parent enterprise.

artistId

Optional

integer

ID for an existing artist to assign as the primary artist for the track.

  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.

tracksLocals

Optional

array of objects

Track name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the track name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).

  • Each object in the array represents the name in a different language.

  • If name or languageId are omitted, the object will be ignored.

Parameter

Type

Description

name

Mandatory

string

Name in the indicated language.

version

Optional

string

Version in the indicated language.

languageId

Mandatory

integer

Language ID indicating the language of the name. Each language can be used only once in the array.

Lookup up the languageId using the GET /common/lookup/languages resource.

artistLocals

Optional

array of objects

Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).

  • Each object in the array represents the name in a different language

Parameter

Type

Description

name

string

Name in the indicated language.

languageId

integer

Language ID indicating the language of the name. Each language can be used only once in the array.

Lookup up the languageId using the GET /common/lookup/languages resource.

contributors

Optional

array of objects

Additional key artists who should be given top level credit. Do not provide individual band member names or supporting musicians.

  • Each object in the array represents a contributor.

  • Legacy contributors: Prior to July 2021, contributors were not added as artists. The contributor object included a name parameter and did not include an artist object. The name parameter directly in the contributor object is deprecated, and should never be used for new contributors. When editing an existing release with legacy contributors, we recommend prompting users for the data required by the artist object and providing the contributor object according to the current standard.

Parameter

Type

Description

contributorId

Optional

GUID

ID for an existing contributor.

  • Not relevant for new releases. Should be provided when editing existing releases.

roleId

Mandatory

integer

  • 5 - Featuring

  • 49 - Primary Artist*

  • 34 - Producer

  • 6 - Remixer

  • 7 - With

*Should only be used to name additional primary artists. The first (or only) primary artist should only be indicated with the artistName parameter.

For information about additional roles, use the GET /common/lookup/contributorRoles resource.

Note that it is strongly encouraged to use a reduced set of contributor roles, such as those visible in the Revelator web interface. Many users will be tempted to add extraneous roles which will result in the release being rejected by top tier DSPs. Furthermore, even though publishing roles do exist for this attribute, they should never be used; publishing credits should be provided per track in the composerContentsDTO array.

artist

Mandatory

object

The contributing artist.

Unlike all other artists in Revelator, contributing artists with any role other than Primary Artist, Featuring, or Remixer DO NOT require external artist IDs. In other words, contributing artists with the roles Primary Artist, Featuring, or Remixer require Apple and Spotify IDs (same as primary artists); contributing artists with other roles do not require these IDs (they are optional).

See Artist Object.

languageId

Mandatory

integer

Language ID for the track's lyrics.

Lookup up the languageId using the GET /common/lookup/languages endpoint. English is 1.

version

Optional

string

Version of the track. For example, Remix or Bonus Track.

explicit

Mandatory

boolean

Whether or not the track is explicit. Should be true when the song contains any of the following:

  • Anything unsuitable for children

  • Strong language

  • References to violence or abuse

  • Sexual content

  • Anything that might be regarded as racist, homophobic, discriminatory or misogynistic

  • Anything that encourages or celebrates criminal behavior

trackType

Optional

integer

One of the following:

  • 1 - Original song. Composition which you’ve contributed lyrics and/or music and does NOT borrow elements from previously created works. (Default)

  • 3 - Public domain song. Composition where the intellectual property rights have expired or been forfeited. Generally applies to songs written before 1923.

artistAppleId

Mandatory

Integer

One of the following:

  • For artists already on Apple Music, existing Apple ID for the artist.

    To find this ID, go to your Apple Music artist page, and copy-paste the numeric part of the URL. Example 1249595

  • For artists not already on Apple Music, 0.

    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.

artistSpotifyId

Mandatory

Integer

One of the following:

  • For artists already on Spotify, existing Spotify ID for the artist.

    To find this ID, go to your Spotify artist page, and copy-paste the numeric part of the URL. Example: 22bE4uQ6baNwSHPVcDxLCe

  • For artists not already on Spotify, 0.

    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.

trackLength

Optional

integer

Length of the track in seconds.

  • Although the track length is optional when creating a track, it is required to distribute it.

sampleRate

Optional

integer

Sample rate of the track in Hz.

  • Although the sample rate is optional when creating a release, it is required to distribute it.

wav or flac

Optional

object

Audio file for the track in WAV or FLAC format.

  • Use the parameter name according to the format of the audio file. The track object should include the wav parameter or the flac parameter (not both).

  • Although the audio file is optional when creating a track, it is required to distribute it.

  • The audio file must be a stereo WAV file or FLAC file. A minimum bit depth of 16 bit and minimum sample rate of 44.1 kHz are recommended.

  • In line with the general behavior of this API, patching is not supported. When editing an existing release associated with an existing file, you must include this object (with the existing fileId and fileName) to prevent the file from being deleted.

See File Object.

composerContentsDTO

Mandatory

array of objects

Publisher information for the track.

Parameter

Type

Description

composerName

Optional

string

Name of the composer.

  • When provided without composerId, tries to find an existing composer with the same name (ASCII SQL). If no such composer is found, creates a new composer and assigns it to the track.

  • When provided with composerId, the name of the existing composer will be updated.

  • When no composerId nor composerName is provided, the entire object in the composerContentsDTO array is ignored. No data in the object will be updated or deleted.

composerId

Optional

integer

ID for an existing composer to assign to the track.

  • When no composerId nor composerName is provided, the entire object in the composerContentsDTO array is ignored. No data in the object with be updated or deleted.

rightsId

Mandatory

integer

Publishing type. One of the following:

  • 1 - Copyright control (self-published)

  • 2 - Published (managed by a publisher)

    See additional required parameters below.

  • 3 - Public domain (no publisher)

roleId

Mandatory

integer

Role of the composer. One of the following:

  • 52 - Adapter

  • 9 - Arranger

  • 2 - Composer

  • 54 - Composer and Arranger

  • 39 - Composer and Lyricist

  • 53 - Income Participant

  • 4 - Lyricist

  • 51 - Sub-Author

  • 50 - Translator

  • 1 - Writer

share

Mandatory

string

Share percentage for the composer. The total percentage for all composers must be 100%.

publisherName

Optional

string

Name of the publisher.

  • Only relevant when rightsId is 2.

  • When provided without publisherId, tries to find an existing publisher with the same name (ASCII SQL). If no such publisher is found, creates a new publisher and assigns it to the composer.

  • When provided with publisherId, the name of the existing publisher will be updated.

  • Either a publisherId or a publisherName must be provided (when rightsId is 2). Otherwise, no publisher is specified (and the metadata for the track will be incomplete).

publisherId

Optional

integer

ID for an existing publisher to assign to the composer.

  • Only relevant when rightsId is 2.

  • Either a publisherId or a publisherName must be provided (when rightsId is 2). Otherwise, no publisher is specified (and the metadata for the track will be incomplete).

isrc

Optional

string

ISRC code for the track. Hyphens and spaces will be automatically removed, and letters will be automatically capitalized.

  • The ISRC is a unique code that every track must have. The system will automatically generate one upon distribution (free of charge) if you omit this parameter. You should never generate a new ISRC for a track that already has one.

  • The format of the ISRC code is CCXXXYYNNNNN, where CC is the country code (letters), XXX is your registrant code (letters and numbers), YY is the year (numbers), and NNNNN is the unique identifier (numbers).

Adding/Editing Artists

An artist is a metadata entity that is referenced in assets (releases and tracks). Use the /content/artist/save resource to create or edit artists.

Note

  • There is no requirement to create artists before creating an asset. Artists can be created with the same API call that creates the asset. When creating or editing an asset, the options for editing existing artists associated with the asset are limited.

  • When you edit an artist that is already associated with assets, all assets will be automatically updated.

POST /content/artist/save

Table 12. Query String Parameters

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.



Table 13. Request Body Parameters

Parameter

Type

Description

name

Optional

string

Name of the artist.

  • When provided without an artistId, tries to find an existing artist with the same name (ASCII SQL). If no such artist is found, creates a new artist.

  • When provided with an artistId, updates the name of the artist.

  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.

  • All artists in child enterprises automatically appear as Rights Holders in the parent enterprise.

artistId

Optional

integer

ID for an existing artist.

  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.

artistExternalIds

Optional*

array of objects

External IDs for the artist.

*Mandatory for all artists, except for contributors with roles other than Primary Artist, Featuring, or Remixer. For all artists where this parameter is mandatory, this array must include an object for every supported store.

  • These IDs are used by the stores to make sure that all of an artist's content stays together. For artists who have not yet distributed to a specific store, we will generate a new ID if/when a release for the artist is distributed to the store.

  • Each object in the array represents an external ID for the artist at a specific store.

Parameter

Type

Description

profileID

Mandatory

integer

One of the following:

  • For an artist already on the store, external ID for the artist at the specified store.

    To find this ID go to the artist's page at the store, and copy-paste the numeric part of the URL

  • For artists not already on the store, 0.

    This indicates we should generate an ID for the artist if/when a release for the artist is distributed to the store.

    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.

distributorStoreId

Mandatory

integer

Revelator ID for the store.

Currently supported for:

  • Apple Music - 1

  • Spotify - 9

artistLocals

Optional

array of objects

Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).

  • Each object in the array represents the name in a different language

Parameter

Type

Description

name

string

Name in the indicated language.

languageId

integer

Language ID indicating the language of the name. Each language can be used only once in the array.

Lookup up the languageId using the GET /common/lookup/languages resource.



Managing External Artist IDs

Some DSPs share their artist IDs with us, allowing us to tightly couple our artists with theirs. This enables us to avoid situations where two different artists with the same name are merged or a single artist's catalog is split between two or more profiles.

If an artist is already on the DSP, we require you to provide this ID when creating releases for the artist. If an artist is not already on the DSP, we require you to indicate that we should generate an ID for the artist when (if ever) the artist is distributed to the DSP.

Note

  • Currently, this is supported for Apple Music and Spotify, only.

  • These IDs must be provided when creating releases, even if you are not sending releases to DSPs via the Revelator system. In this case, the IDs can be assigned the value "0" and will remain with this value.

Distributing additional releases for artists with new IDs

You must retrieve newly generated IDs immediately before distributing additional releases for an artist.

Warning

If the ID for the artist has already been generated, but you continue to indicate that a new ID should be generated, you will delete the ID from the Revelator system and may cause a second ID to be generated for the artist!

  1. Specify the Revelator artistId parameter in the new release to ensure that the same Revelator artist is being assigned.

  2. Immediately before distributing the new release, retrieve the ID with the GET /content/artist/all or GET /content/artist/{Id} endpoint. The response will include the profileId for each DSP. See Artist Object.

    • If the value of the profileId is still 0, the ID for the artist has not yet been generated.

    • If the value of the profileId is >0, this is the generated ID.

    Warning

    Do not continuously poll our system for the ID. Only run the GET request immediately before distributing a new release which requires the ID. There are many reasons that an ID may never be generated (for example, when a Spotify release does not ultimately go live).

    Note

    Different DSPs generate new IDs at different times in the distribution process:

    • For Apple Music, this ID is generated immediately upon distributing the original release. Therefore, as soon as the original release is distributed, the apple ID will be available.

    • For Spotify, this ID is generated when the original release goes live. When relevant, Spotify uses our internal ID to ensure the artist is merged with the correct profile.

  3. Specify the current values for the external IDs in the release metadata.

    If the ID is still 0, the correct ID will be assigned to the artist (and on all releases for the artist) as soon as it is available.

  4. Distribute the new release.

Distributing Releases

Distribution Workflow

Complete the following workflow to distribute a release.

Note

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.

  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 Release Metadata.

    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.

Warning

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

Table 14. URL Parameters

Parameter

Description

releaseId

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



Table 15. Query String Parameters

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.



Table 16. Response

Response Body

  • If the release has no errors: None

  • If the release has errors: See example.



Request
curl -X POST 'http://staging-api.revelator.com/distribution/release/540168/validate?Token=75b399be-a3e7-4785-b0e0-35064b77b7ac' 
Response
JSON
[ 
    { 
        "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

Table 17. Query String Parameters

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.



Table 18. Request Body Parameters

Parameter

Type

Description

releaseId

Mandatory

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

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

saleStartTimezone

Optional

integer

The time zone offset for the saleStartTime. The release will go live at the same instant everywhere.

  • When provided, saleStartTime is mandatory.

  • Along with saleStartTime , specifies the absolute time that the release should go live.

To lookup time zone offsets, use the GET /common/lookup/timezones resource.

monetizationPolicyIds

Mandatory

array of integers

Revelator monetization policy ID(s) for YouTube Content ID and/or Facebook Rights Manager. The array should include no more than one monetization ID for YouTube Content ID and one for Facebook Rights Manager.

  • Parameter is mandatory even if the array is empty.

  • In addition to setting the monetization policy for a store, you must include the store (YouTube Content ID and/or Facebook Rights Manager) in the addtoqueue request. See Adding Releases to the Distribution Queue.

  • Monetization Policy IDs are unique to each account. Your Revelator account manager will provide your monetization IDs when monetization is enabled for your account.

    • It is possible that you may need to apply a different monetization policy for a single track, for example, in a case where a track is a public domain song. In this case, please open a support ticket with the track ISRC.

    • The table below displays some policy possibilities, but other options, such as the ability to apply a different policy to different territories differently, are possible. Please discuss your needs with your account manager.

    Table 19. Example Monetization Policy Descriptions

    Policy Name

    Relevant Store

    Description

    Monetize in all countries

    YT CID

    Receive royalties when tracks are used/played.

    Track in all countries

    YT CID

    Receive analytics for when tracks are used/played.

    Claim Ad earnings

    FRM

    Receive royalties when tracks are used/played.

    Block

    FRM

    Prevent tracks from being used/played.

    Monitor

    FRM

    Receive analytics for when tracks are used/played.





Request
curl -X POST 'http://staging-api.revelator.com/content/release/retail/save'\ 
--header 'Content-Type: application/json'\  
--header 'Accept: application/json'\  
-d '{ "releaseId": 123456, 
      "saleStartDate": "12/11/2020",  
      "saleStartTime": "05:00",
      "saleStartTimezone": 2,  
      "monetizationPolicyIds": [ 333,332] 
 }' 

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.

Note

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.

Warning

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

Table 20. Query String Parameters

Parameter

Description

token

Mandatory

Access token returned upon authentication.

releaseId

Mandatory

The ID of the release to add to the queue. This ID was returned in the /content/release/save request which created the release.



Table 21. 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.



Warning

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

Request
curl -X POST 'http://staging-api.revelator.com/distribution/release/addtoqueue?Token=75b399be-a3e7-4785-b0e0-35064b77b7ac&releaseId=540168' \
-d '[1, 9, 208, 315, 14, 312, 37, 13]

Inspecting and Approving Release Metadata

Releases in the distribution queue will not be sent to stores until a user of your parent account inspects and approves the release's metadata in the Revelator web interface.

Warning

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.

  1. Log in to the parent account in the relevant environment (app.revelator.com or staging.revelator.com).

  2. In the main menu, select Distribution.

    The Distribute page appears.

    distribute.png
  3. Click the Queue tab.

    The Queue tab appears, displaying the To inspect sub tab.

    inspect.png
  4. Select the release in the To inspect sub-tab.

    Release information appears with the Actions button in the upper right corner.

    inspect_details.png
  5. Review the metadata and edit it as needed.

  6. Approve the metadata and send the release on to the store(s) by clicking Actions and selecting Save & deliver.

    The release is sent to the stores.

Retrieving Distribution Status

Use the distribution/store/all resource to get the distribution status for a release.

Note

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

Table 22. Query String Parameters

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.

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

options.status

Optional

The status of the releases for which to get distribution information. Please see the Query String Text in Table 23, “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.

Table 23. Distribution Statuses

Status

Status text

Query string text

Additional 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

Waiting for audio encoding

WaitingForAudioEncoding

 

10

Encoding audio files

EncodingAudio

 

11

Audio encoding failed

EncodingAudioFailed

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.

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

Note

Sometimes YouTube will indicate an error that does not require a fix; it is simply a warning/alert.

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.

  • "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.

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

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

Removed from store

RemovedFromStore

Takedown confirmed by DSP

100

Error in process, please try again.

ProcessError

Processing error



Request
curl -X GET 'http://staging-api.revelator.com/distribution/store/all?options.releaseId=540650&token=2ec6ba54-3199-473a-a129-296bf672a759'\ 
--header 'Accept: application/json'  
Response
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 }

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:

  • Primary artists are the same on the release and tracks (including contributors with the role Primary Artist).

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

Note

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

  2. Resend the release to the store(s). See Adding Releases to the Distribution Queue.

Retrieving Analytics

New Analytics API Coming Soon

Documentation coming soon.

Please contact support for information about the current and/or future analytics API.

Managing Rights

Creating/Editing Contracts

Use the /contract/save resource to add or edit contracts.

Note

  • This endpoint requires a token for the parent account.

    This endpoint can be used to trigger the creation (or modification) of a contract in the parent account as the result of a user action. General creation of contracts is not an activity appropriate for child account users.

  • A default contract and payee are automatically created upon account creation; the contract automatically inherits all assets in the account (that are not explicitly covered by a more specific contract), and the default payee is named as the only payee.

Warning

Unless otherwise stated, the Revelator API does not support partial updates. When editing an object, the existing values of any omitted parameters will be deleted or overwritten, according to the designated behavior for a null value for that parameter. Consequently, we recommend you always query the object you want to edit and modify the JSON object to avoid partial update problems.

The Revelator system provides various contract types, each with a different scheme for specifying which assets are governed by the contract.

  • Account Level. Inherits all assets in an account. This is the default contract that is automatically created upon signup.

  • Label Level. Inherits all assets under a specified label. The contract licensor object has licensorType set to label and allFutureAssets set to true.

  • Artist Level. Inherits all assets for a specified artist; this includes both full releases and individual tracks. The contract licensor object has licensorType set to artist and allFutureAssets set to true.

    Only the primary artist on the asset is used for contract allocation. Contributing artists are ignored, including contributors with the role "primary".

  • Release Level. Includes releases (with all of their tracks) where all the releases are associated with either the same artist or the same label . The contract licensor object has licensorType set to either label or artist and allFutureAssets set to false.

  • Track Level. Includes specific tracks (with or without other full releases) where all of the releases and tracks are associated with either the same artist or the same label. The contract licensor object has licensorType set to either label or artist and allFutureAssets set to false.

    When you create track level contracts, you must ensure that every track and the release itself is named on a contract. This means a minimum of 3 contracts for the release: a contract for the special track(s), a contract for the other track(s), and a contract for the release as a whole. The contract for the release itself should name every payee, and you must manually calculate and provide their prorated share of the release for each payee. (The release level contract is relevant when the whole release is downloaded.)

    Note that even though track level contracts support including full releases, we do not recommend that you include the release itself on a contract when some but not all of the tracks are on a track specific contract. This would complicate the processes of calculating the prorated shares.

Note

Assets will always be subject to the most specific contract that includes the asset. In other words, a track level contract will take precedence over a release level contract, a release level contract will take precedence over an artist level contract, etc.

POST /accounting/contract/save

Table 24. Request Body Parameters

Parameter

Type

Description

name

Mandatory

string

Name of the contract.

contractId

Optional

integer

Id of the existing contract to edit.

  • When set to 0, creates a new contract. (Default)

  • Inline with the general behavior of this API, patching is not supported. Existing values for omitted parameters will be deleted or overwritten.

contractTypeId

Mandatory

integer

1 - specifies a Distribution Agreement.

startDate

Mandatory

string

Date from which the contract is effective, in the format YYYY-MM-DD.

This date is for reference only is not enforced when calculating royalties.

expirationDate

Mandatory

string

Date the contract becomes ineffective, in the format YYYY-MM-DD. If your contract is "in perpetuity", please indicate 2099-12-31.

This date is for reference only is not enforced when calculating royalties.

isActive

Optional

boolean

Whether the contract is active. Inactive contracts are not used for royalty calculations.

  • Always set as true for new contracts.

  • Defaults to false when editing existing contracts.

contractPayees

Mandatory

array of objects; see Contract Payee Object

Each object represents a payee and details their royalty information.

The sum of every non-comission payee's sharePercentage must equal 100.

contractLicensors

Mandatory

array including one object*; see Contract Licensor Object

Object represents a licensor (rights holder) and provides information for which of the licensor's assets should be subject to the contract.

*Although contractLicensors is an array, the array should include only one object. For additional licensors, please create a separate contract.

contractReleases

Optional

array of objects

Specifies which releases should be included in the contract when only some of the licensors assets are included in the contract.

Each object in the array includes a release ID: {"releaseid": <integer>}

  • When all of the licensors assets are included in the contract (includeFutureAssets is true) this parameter is not relevant.

  • When a release is included in this array, every track in the release will automatically be subject to the contract. The release's individual tracks should not additionally be included in the contractTracks array.

contractTracks

Optional

array of objects

Specifies which tracks should be included in the contract when only some of the licensors assets are included in the contract, and only when some of the tracks on releases are included in the contract.

Each object in the array includes a track ID: {"trackid": <integer>}

  • When all of the licensor's assets are included in the contract (includeFutureAssets is true) or only complete releases are included in the contract, this parameter is not relevant.

contractTerms

Mandatory

array of objects; see Contract Terms Object

Specifies terms for the contract.

payMechanicals

Optional

boolean

  • true - to pay digital mechanicals. Additional attributes are required.

  • false - to not pay digital mechanicals (Default)

mechanicalsTypeId

Optional1

integer

Rate type for mechanicals:

  • 1 - % of Sales

  • 2 - Penny Rate

  • 3 - Copyright Law

1Mandatory when payMechanicals is true.

mechanicalsSalesPercentage

Optional2

integer

Sales percent.

2Mandatory when mechanicalsTypeId is 1.

mechanicalsFixedPennyRate

Optional3

integer

Penny rate.

3Mandatory when mechanicalsTypeId is 2.

mechanicalsIsFullRate

Optional4

boolean

Rate basis:

  • true - Full

  • false - Minimum

4Mandatory when mechanicalsTypeId is 3.

mechanicalsRatePercentage

Optional4

integer

Rate percent.

4Mandatory when mechanicalsTypeId is 3.



Request
{
  "contractId": 0,
  "name": "string",
  "contractTypeId": 0,
  "startDate": "2021-10-26T18:19:07.921Z",
  "expirationDate": "2021-10-26T18:19:07.921Z",
  "mechanicalsTypeId": 0,
  "mechanicalsSalesPercentage": 0,
  "mechanicalsIsFullRate": true,
  "mechanicalsRatePercentage": 0,
  "mechanicalsFixedPennyRate": 0,
  "payMechanicals": true,
  "isActive": true,
  "contractTerms": [
    {
      "contractTermsId": "00000000-0000-0000-0000-000000000000",
      "contractTermsRateTypeId": 0,
      "contractTermsRate": 0,
      "isCountriesIncluded": true,
      "isDistributorStoresIncluded": true,
      "countries": [
        0
      ],
      "deliveryTypes": [
        0
      ],
      "releaseTypes": [
        0
      ],
      "distributorStores": [
        0
      ]
    }
  ],
  "contractReleases": [
    {
      "releaseId": 0,
    }
  ],
  "contractTracks": [
    {
      "trackId": 0
    }
  ],
  "contractLicensors": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "licensorType": "Artist",
      "licensorId": 0,
      "includeFutureAssets": true
    }
  ],
  "contractPayees": [
    {
      "sharePercentage": 0,
      "startingBalance": 0,
      "isCommissionPayee": true,
      "permission": {
        "enterpriseId": 0,
        "enterpriseName": "string",
        "labelId": 0,
        "publisherId": 0,
        "artistId": 0,
        "payeeId": 0,
        "imageId": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "permissionsAccountId": "00000000-0000-0000-0000-000000000000",
        "isOwner": true,
        "readOnlyContent": true,
        "readOnlyContracts": true,
        "readOnlyFinance": true,
        "readOnlyDistribution": true,
        "readOnlyPromote": true,
        "readOnlyDaily": true,
        "permissionRolesId": 0,
        "isActive": true,
        "email": "string"
      },
      "payee": {
        "paymentProviderId": 0,
        "paymentUserId": "string",
        "currencyCode": "string",
        "contact": {
          "contactId": 0,
          "name": "string",
          "currencyCode": "string",
          "email": "string"
          },
        "payeeId": 0,
        "companyName": "string"
      }
    }
  ]
}

Contract Payee Object

Parameter

Type

Description

sharePercentage

Optional

integer

  • For standard payees (non-commission), the percent of the payee revenue that will go to this payee.

  • For commission payees, the percent of the payor revenue that will go to this payee.

Defaults to 0.

startingBalance

Optional

integer

The payee's starting balance. Defaults to 0.

isCommissionPayee

Optional

boolean

  • true - the payee is a commission payee, and will be paid from the payor's share of the revenue.

  • false - the payee is a standard payee (Default)

payee

Mandatory

object; see Payee Object

Details of the payee.

permission

Optional

object

The permissions the payee has in their payee portal.

This parameter sets permissions for the payee to log into the Revelator UI. It is not relevant for most API use cases, and is never relevant when the payee already has a user/child account that was created with the signup resource.

Payee Object

Parameter

Type

Description

payeeId

Optional

integer

ID for an existing payee to associate with the contract.

  • When set to 0, creates a new payee. (Default)

A default payee (and default contract) is automatically created upon account creation. You should never create a new payee for a user for whom you have already created a child account.

companyName

Mandatory

string

Name of the payee. When omitted, defaults to the name of the contact.

contact

Mandatory

object

Contact information for the payee.

Parameter

Type

Description

contactId

Optional

integer

ID for an existing contact.

  • When set to 0, creates a new contact (Default)

name

Optional

string

Name of the contact.

Defaults to the companyName.

email

Optional

string

Contact's email address.

This email is used for sending statement notifications when automatic email notifications are enabled.

currencyCode

Optional

integer

Currency code for the payee's currency. Defaults to the parent account's currency code.

Look up currency codes using the GET /common/lookup/currencies resource.

paymentProviderId

Optional

integer

  • 2 - paypal

Only necessary when using the Paypal integration for paying the payee.

paymentUserId

Optional

string

Paypal email address for the payee.

Only necessary when using the Paypal integration for paying the payee.

Contract Licensor Object

Parameter

Type

Description

id

Optional

GUID

ID for an existing contract licensor entity.

Not relevant for new contracts. Should be provided when editing existing releases.

licensorType

Mandatory

integer

Type of licensor that will be used to specify the assets to include in the contract.

  • 1 - artist*

  • 2 - label

* For artist licensors, you can only specify assets where the artist is the primary artist on the release level. Therefore, compilations cannot be specified for artist licensors. Additionally, when includeFutureAssets is true, only the primary artist on the asset is considered; contributors are ignored, including contributors with the role "primary".

licensorId

Mandatory

string

ID of the licensor. Either an artistId or labelId, according to the licensorType.

includeFutureAssets

Optional

boolean

  • true - to include all of the licensor's current and future assets

    When this is true for a licensor, none of the licensor's assets should be included in the contractReleases or contractTracks arrays.

  • false - to not include all of the licensor's current and future assets (Default)

Contract Terms Object

Parameter

Type

Description

contractTermsId

Optional

GUID

ID for an existing contract terms entity.

  • Not relevant for new contracts. Should be provided when editing existing releases.

contractTermsRate

Optional

integer

Percent of the revenue being paid out to payees. Defaults to 0.

contractTermsRateTypeId

Mandatory

integer

  • 1 - to calculate the payout with retail

  • 2 - to calculate the payout with wholesale

isCountriesIncluded

Optional

boolean

  • true - the countries array provides the only territories included in the contract

  • false - the countries array provides the only territories excluded by the contract, and all other countries are included (Default)

    To include all territories in the contract, set isCountriesIncluded to false and leave countries empty.

isDistributorStoresIncluded

Optional

boolean

  • true - the distributorStores array provides the only services included in the contract

  • false - the distributorStores array provides the only DSPs excluded by the contract, and all other DSPs are included (Default)

    To include all DSPs in the contract, set isDistributorStoresIncluded to false and leave distributorStores empty.

countries

Optional

array of integers

IDs for the countries included or excluded from the contract. See isCountriesIncluded.

Lookup country IDs using the GET /common/lookup/countries resource.

distributorStores

Optional

array of integers

IDs for the services included or excluded from the contract. See isDistributorStoresIncluded.

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.

releaseTypes

Optional

array of integers

Types of releases to include in the contract terms:

  • 1 - Album

  • 2 - Single

  • 4 - EP

An empty array will cause all types to be included for the contract. (Default)

deliveryTypes

Optional

array of integers

Delivery channels to include in the contract terms. Each integer in the array is an ID that represents a delivery type; each channel includes multiple delivery types.

  • Download: 101,106, 123

  • Subscription: 102,104,105,107

  • Ad supported: 103, 115, 109, 118

  • Physical: 110

  • Rental: 116

  • Digital Licensing: 117

  • UGC: 120

An empty array will cause all types to be included for the contract. (Default)