Developer Help Center

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.

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

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.

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

GUI ID

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