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

Base URLs

Sandbox

All testing should be done in a production environment using a dedicated sandbox account. If you do not already have a sandbox account, please contact us at [email protected] to create one.

A staging environment was previously used for this purpose. This is no longer supported.

Authentication and Headers

Access Tokens

Retrieve an access token for a user by Authenticating.

The access token must be sent with each subsequent request as an Authorization header with the value set to

Bearer <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.
• Assets will never be defined directly in the parent account. Parent account users have permission to view and edit all child account content (releases, tracks, artists and labels), as well as view analytics.
• Required model for any use case which involves directing your users to the Revelator web interface (white labels).
• 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 and performing royalty runs, in the partner tenant in the Revelator web interface.
• Recommended for customers seeking to utilize built-in automation, such as default contracts per child account

Other Models

Different implementation models do exist, but are not recommended in most cases. If the Child Account Model doesn’t work for you, please contact your API account manager.

Workflow: Importing an Existing Catalog or Creating New Release

Use this workflow to understand the order of API requests to use when importing an existing catalog or creating new releases. To import an existing catalog, use these requests in your ingestion script; otherwise, use this request flow in your application.

For standalone accounts, skip to step 2.

1. Signup up a new user. See Signing Up New Users.
2. Authenticate. See Authenticating.
3. Create artists (Optional). See Adding/Editing Artists.

4. Create releases. Adding/Editing Releases.

Workflow: Customizing Signup/Login for White Labels

To create a custom signup and login page

1. Implement signup. See Signing Up New Users

   • If maintaining separate database of user credentials, use unprompted option.
   • If not maintaining separate database of user credentials, use prompted option.

2. Implement authentication. See Authenticating.

   • If maintaining separate database of user credentials, use unprompted option.
   • If not maintaining separate database of user credentials, use prompted option.

3. Implement Forgot Password sequence.

   • For unprompted implementations, the Revelator API is not relevant.
   • For prompted implementations, see Security and passwords

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

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.

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 Label/Artist, Payee, and Contract.
   • The default Contract covers all assets created in the account (until/unless more specific contracts are defined).
   • The default Payee receives 100% of the royalties being paid by the default Contract (until/unless additional payees are specified).
   • The Content, Payee, and Contract will all be visible in the parent account.

POST /partner/account/signup

Request Body

Response

Body (success)

HTTP Codes

curl -iv -X POST "https://api.revelator.com/partner/account/signup"\
-H "Accept:application/json"\
-H "Content-Type:application/json" \
-d '{ "email":"[email protected]",
    "password":"password123",
    "enterpriseName": "John Doe Band",
    "firstname":"John",
    "lastname": "Doe",
    "type":"Launch",
    "partnerApiKey":"00000000-0000-0000-0000-000000000000",
    "partnerUserId":"XXXXX",
    "defaultContractTermsRate": 85.5
}'

{
    "userId": "a57cbed3-3bf1-4ada-b16c-40d0320bfc8cb",
    "enterpriseId": 123456
}

Upgrading Accounts

POST /partner/account/upgrade

Request Body

Response

Body

HTTP Codes

Authenticating

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

Which method to employ will depend on your use case; using both methods simultaneously will fail.

POST /partner/account/login

There are two ways to generate an accessToken.

1. Prompted login - provide a username and password.
2. Unprompted login - provide partnerUserId.

Request Body

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

{
  "accessToken": "string",
  "permissions": [
    {
      "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,
      "isDefault": true,
      "email": "string",
      "accountType": 0
    }
  ],
  "isAuthorized": true
}

Supporting User Invites

An invitation is when a current user invites another member to their account using the Revelator Pro UI.

You can now manage the email template and invite link directly from your tenant settings in the platform.

Invited User Workflow

1. When a user is invited, they receive an email containing a link to your custom login page. This email also includes their email address (used as a username) and a temporary password generated by Revelator. The user should change this password after the first login.

   • Example link: https://examplelabel.com/invitation?email={invitedUserEmail}&code={invitationCode}

2. When the user lands on your custom login page, make sure to update the partnerUserId to a value that matches your internal system. (The logic is the same as described in Signing up new users).

• Call the GET /partner/invitation to retrieve the automatically assigned partnerUserId

• Call the POST /partner/users to update the partnerUserId

  ⚙️ These API calls must be performed from your backend to avoid exposing your Partner API Key in client-side code.

3. Once updated, the user can Authenticate.

Invitation Expiration and Resending

By default, invitations expire 24 hours after being sent. If not accepted within that period, the link becomes invalid and authentication attempts will result in an error.

The expiration time can be customized on request, and invitations can be re-sent.

GET /partner/invitation

Retrieves the information about a user invitation.

Query Params

Response

POST /partner/users

Update the user partnerUserId and/or password

Request body

Security and passwords

Password complexity requirements

Passwords must meet the following requirements:

• At least 8 characters long
• Include a lowercase letter
• Include an uppercase letter
• Include at least one special character (!@#$%^&*)
• Include at least one number (0–9)

Forgotten password workflow

1. Add a “Forgot password” link to your custom login page that uses the POST /account/forgotpassword endpoint.
2. The user will receive an email to complete the password reset process.

This endpoint can only be used if your account has Revelator’s transactional email service configured.

POST /account/forgotpassword

Initiates the forgotten password flow.

Query String Parameters

Redirecting Authenticated Users to the Web Interface

Once you have validated a user’s credentials and authenticated them successfully, you can redirect the user to their account in the Revelator web interface.

To load the user’s account, include the access token (retrieved during authentication) in the redirect URL.

Important Notes

• Always use your custom production URL (your White Label domain) to load the interface with your brand’s customizations.
• If a user has access to multiple Revelator accounts, their default account will be loaded. They can switch between accounts once inside the interface.

Authorization URL Structure

The base URL for redirecting an authenticated user is:

URL Query Parameters

The following query parameters are available for use in the authorization URL:

Example Format:

https://<custom_v2_url>/authorize?token=00000000-0000-0000-0000-000000000000&redirectUrl=https://<custom_v2_url>/analytics/consumption/dashboard

Running Requests in Child Accounts

API partners using the Child Account model often need to perform API requests on behalf of specific child enterprises. In most cases, this can be done indirectly, without using the special /api/enterprises/{enterpriseId}/ prefix.

Running Requests Indirectly

Many endpoints already allow you to target a child enterprise by including an identifier in the request:

• Use an enterpriseId field in the request body, for example when creating or updating a composer via POST /content/composer/save.
• Use the enterprises query parameter on certain GET endpoints, such as GET /content/release/all, to retrieve data from multiple child enterprises at once.

Always refer to the individual endpoint documentation to confirm whether a request supports these parameters.

Running Requests via the Enterprise Prefix

If an endpoint does not natively accept an enterpriseId or similar parameter, you can explicitly run the request in the context of a child account using the full endpoint path format:

<base_url>/api/enterprises/{enterpriseid}/<documented_path>

Example: To create an artist in a child account with ID 12345, call <base_url>/api/enterprises/12345/artists.

Notes on Behavior

• This method is only supported by certain endpoints (listed below).
• Parent account users can already perform actions that reference existing resources (e.g., validating a release) without using this prefix.
• Some endpoints are only meaningful for parent account users when a target enterprise is specified, since parent accounts themselves do not contain assets, artists, or labels. For example, creating an artist without specifying an enterpriseId will fail when using a parent account token.

Supported Endpoints

The following documented endpoint paths currently support execution in a child account context using the /api/enterprises/{enterpriseid}/ prefix:

• GET /artists
• GET /artists/summary
• GET /artists/{artistId}
• POST /artists
• GET /analytics/{dataSet}/{aggregationDimension}

We are actively working to extend this functionality to additional endpoints. Please refer to the individual endpoint documentation for the most accurate and up-to-date information.

Retrieving Client Information

GET /enterprise/clients/{enterpriseId}

Retrieves the information about a client

Response

GET /enterprise/clients/all

Retrieves the information about all clients

Query Params

Response

GET /partner/users

Retrieves key identifiers for a user based on their email address.

Query Params

Response

Account Termination

POST /api/enterprises/{enterpriseId}/terminate

Terminate the account, reject all releases in the inspection queue, and take down all live catalog

Common resources

Revelator API implementations can use the following common resources to retrieve information about various entities. These are usually used obdain Enum/ID values to be used in other API requests.

GET /common/lookup/currencies

Retrieves a list of all supported currencies.

GET /common/lookup/countries

Retrieves a list of all supported countries.

GET /common/lookup/timezoneIds

Retrieves a list of all supported timezones.

GET /common/lookup/musicstyles

Retrieves a list of all supported music styles.

GET /common/lookup/pricetiers

Retrieves a list of all supported price tiers.

GET /common/lookup/languages

Retrieves a list of all supported languages.

GET /common/lookup/stores

Retrieves a list of all supported DSPs for the account.

GET /common/lookup/contributorRoles

Retrieves a list of all supported contributor roles.

GET /common/lookup/MonetizationPolicies

Retrieves a list of all monetization policies for the account.

GET /common/lookup/trackProperties

Retrieves a list of all track properties for the account.

GET /common/lookup/ContributorRolesGroups

Retrieves a list of all available Contributor Role Groups, each with its ID and name.

GET /common/lookup/contactRoles

Retrieves a list of all available Contact Roles, each with its ID and name.

GET /content/track/lookups

Retrieves a list of various lookup data related to track content, used for dropdowns or selections when managing track metadata.