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

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.

Service	Production	Staging
API	app-api.revelator.com	staging-api.revelator.com
Revelator Web Interface - v2	app.revelator.pro	staging.revelator.pro
Revelator Web Interface - v1	app.revelator.com	staging.revelator.com

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.

Prompted vs Unprompted Signup

↓

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.

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.

POST /partner/account/signup

Request Body

Parameter	Type	Description
email required	string	Unique email for the account owner
password required	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 required	string	The 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	string	Contact 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	object	Payment settings for the account’s default payee (Required to trigger payments directly from Revelator)
paymentSettings.providerId required	integer	ID for the payment provider: 2 - Paypal
paymentSettings.userId required	string	Payment provider’s ID for the user, such as their email address.
firstname optional	string	User’s first name.
lastname optional	string	User’s last name.
type required	string	The 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	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.
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 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.

Response

Body (success)

Parameter	Type	Description
userId	string	Unique email for the account owner
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	Success
403	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.

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

Parameter	Type	Description
partnerAPIKey required	string	API key provided by your Revelator account manager.
enterpriseId required	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 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	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.
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 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.

Response

Body

No Body

HTTP Codes

Code	Description
204	Success
403	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	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.

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

Prompted vs Unprompted Login

↓

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

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

For more information about signup, see Signing Up New Users

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

Parameter	Type	Description
partnerUserId unprompted	string	partnerUserId value assigned to the user in the signup resource. See Signing Up New Users.
partnerApiKey required	string	API key provided by your Revelator account manager. Contact your account manager for assistance.
username prompted	string	user’s email
password prompted	string	user’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

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

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)

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

3. The user can now Authenticate.

GET /partner/invitation

Retrieves the information about a user invitation.

Query Params

Query Param	Type	Description
email required	string	User email.
code required	string	Invitation code

Response

Parameter	Type	Description
partnerUserId	string	User partner ID
email	string	User email
invitedEnterpriseId	integer	The enterpriseId of the enterprise the user was invited to
passwordCanBeReset	boolean	Can you reset the user password
enterprises	array of objects	All enterprises the user has access to.
enterprises.id	integer	Enterprise ID
enterprises.name	string	Enterprise name
enterprises.accessType	string	What kind of access the user has to this enterprise

POST /partner/users

Update the user partnerUserId and/or password

Request body

Parameter	Type	Description
partnerUserId required	string	Current partner user ID
newPartnerUserId optional	string	New partner user ID
newPassword optional	string	New password

Security and passwords

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

Password complexity requirements

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.

Query String Parameters

Parameter	Type	Description
email required	string	Unique email of the account owner
enterpriseId optional	string	Revelatorenterprise 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	string	URL to load after flow completes

Redirecting Authenticated Users to the Web 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.

Redirecting to v2

Production	https://<custom_v2_url>/authorize?token=<access_token>
Staging	https://staging.revelator.pro/authorize?token=<access_token>

Redirecting to v1

Production	https://<custom_v1_url>/Home/IndexWithToken?serverToken=<access_token>
Staging	https://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.

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

Field	Type	Description
enterpriseId	integer	The unique identifier of the enterprise
payeeId	integer	A unique payee ID for the default payee associated with the client
name	string	The name of the client
creationDate	string	The date when the client was created
infringementTrustScore	integer	The trust score associated with the client

GET /enterprise/clients/all

Retrieves the information about all clients

Query Params

Parameter	Type	Description
pageNumber optional	integer	The page number of the results. Default is 1.
pageSize optional	integer	The number of items per page. Default is a system-defined value.
query optional	string	A query string for filtering clients based on specific criteria.

Response

Field	Type	Description
totalItemsCount	integer	The total number of client items available across all pages.
pageNumber	integer	The current page number.
pageSize	integer	The number of items per page
items	array of objects	An array of client objects
items.enterpriseId	integer	The unique identifier of the enterprise
items.payeeId	integer	A unique payee ID for the default payee associated with the client
items.name	string	The name of the client
items.creationDate	string	The date when the client was created
items.infringementTrustScore	integer	The trust score associated with the client
additionalCounters	object	An object containing additional counters
additionalCounters.unfilteredClientsTotal	integer	The total number of clients before any filtering is applied

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.

Field	Type	Description
code	string	Currency code
symbol	string	Symbol for the currency
name	string	Name of the currency
countryCode	string	Country code associated with the currency (empty string if not applicable)

GET /common/lookup/countries

Retrieves a list of all supported countries.

Field	Type	Description
countryId	number	Country ID
isO2Code	string	Two letter country code
code	string	Full country code
name	string	Name of the country

GET /common/lookup/timezoneIds

Retrieves a list of all supported timezones.

Field	Type	Description
timezoneId	number	Timezone ID
text	string	Textual representation of the timezone

GET /common/lookup/musicstyles

Retrieves a list of all supported music styles.

Field	Type	Description
musicStyleId	number	Music style ID
name	string	Name of the music style
parentId	number	Parent music style ID (null if no parent)
order	integer	Numeric order of the music style within the Revelator system

GET /common/lookup/pricetiers

Retrieves a list of all supported price tiers.

Field	Type	Description
priceTierId	number	Price tier ID
name	string	Name of the price tier
code	string	Code of the price tier
isForRelease	boolean	Whether the price tier is for releases
isForTrack	boolean	Whether the price tier is for tracks
price	float	Price of the price tier
distributionStoreIds	integer	Store ID for the DSP that the price tier is available for
order	integer	Numeric order of the price tier within the Revelator system

GET /common/lookup/languages

Retrieves a list of all supported languages.

Field	Type	Description
languageId	number	Language ID
name	string	Name of the language
languageCode	string	Short language code
isValidMetadataLanguage	boolean	Whether the language is valid for metadata

GET /common/lookup/stores

Retrieves a list of all supported DSPs for the account.

Field	Type	Description
distributorStoreId	number	Distributor store ID
name	string	Name of the distributor store
isActive	boolean	Whether the distributor store is active for distribution
shortDescription	string	Short description of the distributor store (null if no description is available)
display	boolean	Whether the distributor store is displayed in the UI
supportRingtones	boolean	Whether the distributor store supports ringtones
supportVideos	boolean	Whether the distributor store supports videos
isNew	boolean	Whether the distributor store is new (null if not new)
deliveryLeadTimeDays	integer	Lead time for delivery in days (null if not applicable)
takedownLeadTimeDays	integer	Lead time for takedown in days (null if not applicable)

GET /common/lookup/contributorRoles

Retrieves a list of all supported contributor roles.

Field	Type	Description
roleId	number	Contributor role ID
name	string	Name of the contributor role
priority	integer	Priority of the contributor role

GET /common/lookup/MonetizationPolicies

Retrieves a list of all monetization policies for the account.

Field	Type	Description
distributorStoreId	number	ID of a distributor store associated with the monetization policy
policyId	number	Monetization policy ID
name	string	Name of the monetization policy
orderNum	integer	Numeric order of the monetization policy within the Revelator system

GET /common/lookup/trackProperties

Retrieves a list of all track properties for the account.

Field	Type	Description
items	array of objects	A parent field containing all track properties
items.trackPropertyId	number	Track property ID
items.name	string	Name of the track property