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

Supporting User Invites

(BETA)

This feature is still in beta. If you encounter any issues please reach out to us.

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

You will need to contact us to configure the email template and include a new invite link that supports this behavior (Step 1 of the Workflow).

Invited User Workflow

  1. The invited user would be created and get an email containing a link to the custom login page. This email also includes the user email (which acts as a username) and a temporary password. (the password is generated by Revelator automatically and should be changed)

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

  2. The user would land on your custom login page. At this point its crucial to update the partnerUserId to a value matching your internal system. (The logic behind this parameter is the same as in the Signing up new users section)

Make sure you make the API calls on the backend to not expose your Partner API Key

  • Call the GET /partner/invitation to retrieve the automatically assigned partnerUserId
  • Call the POST /partner/users to update the partnerUserId
  1. The user can now Authenticate.

GET /partner/invitation

Retrieves the information about a user invitation.

As this is an administrative endpoint. Provide your partnerApiKey as a Bearer token.

Query Params

Query ParamTypeDescription
email
required
stringUser email.
code
required
stringInvitation code

Response

ParameterTypeDescription
partnerUserId
stringUser partner ID
email
stringUser email
invitedEnterpriseId
integerThe enterpriseId of the enterprise the user was invited to
passwordCanBeReset
booleanCan you reset the user password
enterprises
array of objectsAll enterprises the user has access to.
enterprises.id
integerEnterprise ID
enterprises.name
stringEnterprise name
enterprises.accessType
stringWhat kind of access the user has to this enterprise

POST /partner/users

Update the user partnerUserId and/or password

As this is an administrative endpoint. Provide your partnerApiKey as a Bearer token.

Request body

ParameterTypeDescription
partnerUserId
required
stringCurrent partner user ID
newPartnerUserId
optional
stringNew partner user ID
newPassword
optional
stringNew password

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
enterpriseIdintegerThe unique identifier of the enterprise
payeeIdintegerA unique payee ID for the default payee associated with the client
namestringThe name of the client
creationDatestringThe date when the client was created
infringementTrustScoreintegerThe trust score associated with the client

GET /enterprise/clients/all

Retrieves the information about all clients

Query Params

ParameterTypeDescription
pageNumber
optional
integerThe page number of the results. Default is 1.
pageSize
optional
integerThe 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
totalItemsCountintegerThe total number of client items available across all pages.
pageNumberintegerThe current page number.
pageSizeintegerThe number of items per page
itemsarray of objectsAn array of client objects
items.enterpriseIdintegerThe unique identifier of the enterprise
items.payeeIdintegerA 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.infringementTrustScoreintegerThe trust score associated with the client
additionalCountersobjectAn object containing additional counters
additionalCounters.unfilteredClientsTotalintegerThe 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

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.

Some endpoints require an access_token and provide results specific to the account.

GET /common/lookup/currencies

Retrieves a list of all supported currencies.

FieldTypeDescription
codestringCurrency code
symbolstringSymbol for the currency
namestringName of the currency
countryCodestringCountry code associated with the currency (empty string if not applicable)

GET /common/lookup/countries

Retrieves a list of all supported countries.

FieldTypeDescription
countryIdnumberCountry ID
isO2CodestringTwo letter country code
codestringFull country code
namestringName of the country

GET /common/lookup/timezoneIds

Retrieves a list of all supported timezones.

FieldTypeDescription
timezoneIdnumberTimezone ID
textstringTextual representation of the timezone

GET /common/lookup/musicstyles

Retrieves a list of all supported music styles.

FieldTypeDescription
musicStyleIdnumberMusic style ID
namestringName of the music style
parentIdnumberParent music style ID (null if no parent)
orderintegerNumeric order of the music style within the Revelator system

GET /common/lookup/pricetiers

Retrieves a list of all supported price tiers.

FieldTypeDescription
priceTierIdnumberPrice tier ID
namestringName of the price tier
codestringCode of the price tier
isForReleasebooleanWhether the price tier is for releases
isForTrackbooleanWhether the price tier is for tracks
pricefloatPrice of the price tier
distributionStoreIdsintegerStore ID for the DSP that the price tier is available for
orderintegerNumeric order of the price tier within the Revelator system

GET /common/lookup/languages

Retrieves a list of all supported languages.

FieldTypeDescription
languageIdnumberLanguage ID
namestringName of the language
languageCodestringShort language code
isValidMetadataLanguagebooleanWhether the language is valid for metadata

GET /common/lookup/stores?token=<access_token>

Retrieves a list of all supported DSPs for the account.

FieldTypeDescription
distributorStoreIdnumberDistributor store ID
namestringName of the distributor store
isActivebooleanWhether the distributor store is active for distribution
shortDescriptionstringShort description of the distributor store (null if no description is available)
displaybooleanWhether the distributor store is displayed in the UI
supportRingtonesbooleanWhether the distributor store supports ringtones
supportVideosbooleanWhether the distributor store supports videos
isNewbooleanWhether the distributor store is new (null if not new)
deliveryLeadTimeDaysintegerLead time for delivery in days (null if not applicable)
takedownLeadTimeDaysintegerLead time for takedown in days (null if not applicable)

GET /common/lookup/contributorRoles

Retrieves a list of all supported contributor roles.

FieldTypeDescription
roleIdnumberContributor role ID
namestringName of the contributor role
priorityintegerPriority of the contributor role

GET /common/lookup/MonetizationPolicies?token=<access_token>

Retrieves a list of all monetization policies for the account.

FieldTypeDescription
distributorStoreIdnumberID of a distributor store associated with the monetization policy
policyIdnumberMonetization policy ID
namestringName of the monetization policy
orderNumintegerNumeric order of the monetization policy within the Revelator system

GET /common/lookup/trackProperties

Retrieves a list of all track properties for the account.

FieldTypeDescription
itemsarray of objectsA parent field containing all track properties
items.trackPropertyIdnumberTrack property ID
items.namestringName of the track property