Getting Started

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

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

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.

ServiceProductionStaging
APIapp-api.revelator.comstaging-api.revelator.com
Revelator Web Interface - v2app.revelator.prostaging.revelator.pro
Revelator Web Interface - v1app.revelator.comstaging.revelator.com

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

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

This is the model we recommend for most use cases.

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.

Make sure to create artists before creating tracks/releases when running an ingestion script, to avoid race conditions. Failing to create artists before creating content can cause duplicate artists to be created when multiple requests are run in quick succession.

  1. Create releases. Adding/Editing Releases.

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

Workflow: Customizing Signup/Login for White Labels

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.

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 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 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.
Prompted vs Unprompted Signup

POST /partner/account/signup

Request Body

ParameterTypeDescription
email
required
stringUnique email for the account owner
password
required
stringUser’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
required
stringThe name of the artist, manager or label represented by the account.
This will be the name of the Artist/Label, Payee, and Contract automatically created with the account.
statementEmailAddress
optional
stringContact email address for the account’s default payee.
  • When null, defaults to the value provided for email
  • When email notifications are enabled, statement notifications will be sent to this email address.
paymentSettings
optional
objectPayment settings for the account’s default payee (Required to trigger payments directly from Revelator)
paymentSettings.providerId
required
integerID for the payment provider:
  • 2 - Paypal
paymentSettings.userId
required
stringPayment provider’s ID for the user, such as their email address.
firstname
optional
stringUser’s first name.
lastname
optional
stringUser’s last name.
type
required
stringThe type of child account to create.
  • Launch - Account for a single label. The label field for each release will be locked to only allow the label that is created upon signup, which has the same name as the account itself (enterpriseName).
  • Growth - Account for multiple labels.
partnerAPIKey
required
stringAPI key provided upon onboarding.
partnerUserId
optional
stringUnique 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
integerMaximum 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
objectControls 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.
storeAccess.type
required
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
storeAccess.storeIds
required
array of integersThe 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.

Response

Body (success)
ParameterTypeDescription
userIdstringUnique email for the account owner
enterpriseIdintegerThe 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
CodeDescription
204Success
403If 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.

Example

Request
curl -iv -X POST "https://staging-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"
}’
Response
{ 
    userId: "a57cbed3-3bf1-4ada-b16c-40d0320bfc8cb",
    enterpriseId: 123456
}

Upgrading Accounts

POST /partner/account/upgrade

Request Body

ParameterTypeDescription
partnerAPIKey
required
stringAPI key provided by your Revelator account manager.
enterpriseId
required
integerThe 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
stringThe 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 artists and labels; the initial artist/label that was created with the signup request will not be impacted in anyway, and no additional artist/label will be created with this request.
newMaxArtists
optional
integerMaximum 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
objectControls which digital service providers (DSPs) the child account can distribute to. By default, this value will not be updated for the account.
newStoreAccess.type
required
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
newStoreAccess.storeIds
required
array of integersThe 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.

Response

Body
No Body
HTTP Codes
CodeDescription
204Success
403If 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.
409If 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.

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

Prompted vs Unprompted Login

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

ParameterTypeDescription
partnerUserId
unprompted
stringpartnerUserId value assigned to the user in the signup resource. See Signing Up New Users.
partnerApiKey
required
stringAPI key provided by your Revelator account manager. Contact your account manager for assistance.
username
prompted
stringuser’s email
password
prompted
stringuser’s password

Note: When partnerUserId, username and password are all entered, login will fail. Either use prompted (username and password) or unprompted (partnerUserId).

Example

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

Security and passwords

This section is only relevant for API partners without their own user database (prompted implementations).

Password complexity requirements

  • Must be at least 8 characters long
  • Must include a lowercase letter
  • Must include an uppercase letter
  • Must include a special character !@#$%^&*
  • Must include a number 0-9

Forgotten password workflow

  1. Add a forgot password link to your custom login page using the POST /account/forgotpassword endpoint.
  2. The user will get an email to complete the flow

POST /account/forgotpassword

Initiates the forgotten password flow.

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

For security reasons, the endpoint will always return an HTTP code of 200, regardless of whether the email exists in our system.

Query String Parameters

ParameterTypeDescription
email
required
stringUnique email of the account owner
enterpriseId
optional
stringRevelatorenterprise ID
  • When enterpriseId is provided, it is used to determine which White Label template is used for the generated email.
  • When enterpriseId is omitted, it is inferred from the origin header address. If the origin does not match a known White Label, the email will be generated with generic Revelator branding.
redirect
optional
stringURL to load after flow completes

Redirecting Authenticated Users to the Web Interface

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 retrieved upon authentication in the appropriate URL.

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

Redirecting to v2

Productionhttps://<custom_v2_url>/authorize?token=<access_token>
Staginghttps://staging.revelator.pro/authorize?token=<access_token>

Redirecting to v1

Productionhttps://<custom_v1_url>/Home/IndexWithToken?serverToken=<access_token>
Staginghttps://staging.revelator.com/Home/IndexWithToken?serverToken=<access_token>

Deep Linking in v1. 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

Running Requests in Child Accounts

API partners using the Child Account model will likely want to run API requests in individual child accounts. In most cases, this should be accomplished by authenticating the child account user and providing that access token in the request. The account associated with the token will always be the default account for all API requests.

Parent account users, in addition to having permissions in the parent account, have permissions in their child accounts. If you are using the API to create an administrator interface, you may want to allow authenticated parent account users to perform tasks in child accounts.

  • This method is not relevant for all endpoints. All supported endpoints link to this procedure.
  • Parent account users can perform tasks on releases in child accounts without needing this method when the task only references a specific release or track (and does not reference artists or labels) . For example, the endpoint for validating releases does not support this method, but it is irrelevant because a parent account user can freely run the validate endpoint for any release in any of their child accounts.
  • Some endpoints are only relevant for parent account users when a target child enterprise is provided. This is because parent accounts never have any assets, artists, or labels defined in them directly. For example, creating an artist with a parent account user’s token and without providing a target enterpriseId in the URL path will always fail.

To run an API request in a child account with a parent account user’s access token

  • Use the full endpoint path to provide the enterpriseId for the target child account with the documented endpoint path:

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

Example. To create an artist in child account 12345, use the URL <base_url>/api/enterprises/12345/artists

Retrieving Client Information

GET /enterprise/clients/{enterpriseId}

Retrieves the information about a client

Response

FieldTypeDescription
enterpriseIdnumberThe unique identifier of the enterprise
payeeIdnumberA unique payee ID for the default payee associated with the client
namestringThe name of the client
creationDatestringThe date when the client was created
infringementTrustScorenumberThe trust score associated with the client

GET /enterprise/clients/all

Retrieves the information about all clients

Query Params

ParameterTypeDescription
pageNumber
optional
numberThe page number of the results. Default is 1.
pageSize
optional
numberThe number of items per page. Default is a system-defined value.
query
optional
stringA query string for filtering clients based on specific criteria.

Response

FieldTypeDescription
totalItemsCountnumberThe total number of client items available across all pages.
pageNumbernumberThe current page number.
pageSizenumberThe number of items per page
itemsarray of objectsAn array of client objects
items.enterpriseIdnumberThe unique identifier of the enterprise
items.payeeIdnumberA unique payee ID for the default payee associated with the client
items.namestringThe name of the client
items.creationDatestringThe date when the client was created
items.infringementTrustScorenumberThe trust score associated with the client
additionalCountersobjectAn object containing additional counters
additionalCounters.unfilteredClientsTotalnumberThe total number of clients before any filtering is applied

Takedowns and Termination

POST /api/enterprises/{enterpriseId}/terminate

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