Catalog management

Adding/Editing Releases

A release is an album, EP, or single. Releases contain one or more tracks and various metadata. Use the /content/release/save resource to create or edit releases. Specifically, this resource enables you to do the following:

POST /content/release/save

Request Body

Parameter	Type	Description
name required	string	Title of the Release. Required for new releases. When provided with an existing releaseId, updates the name of the release.
releaseId optional	integer	ID for the existing release you want to edit. This ID was returned in the response when the release was created. When set to 0, creates a new release. (Default) Inline with the general behavior of this API, patching is not supported. Existing values for omitted parameters will be deleted or overwritten.
artistName optional	string	Name of the release’s primary artist/band. Should be only the name of oneartist. 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 (case-insensitive). 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. Should be omitted for compilations. Otherwise, either an artistName or artistId must be provided. If neither are provided, the artist will be null, and this is only valid for compilations. All artists in child enterprises automatically appear in the parent enterprise.
artistId optional	integer	ID for an existing artist to assign as the primary artist for the release. Should be omitted for compilations. Otherwise, either an artistName or artistId must be provided. If neither are provided, the artist will be null, and this is only valid for compilations.
releasesLocals required	array of objects	Release name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the release 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). Parameter is mandatory even if the array is empty. Parameter is mandatory even if the array is empty. Each object in the array represents the name in a different language. If name or languageId are omitted, the object will be ignored.
releasesLocals.name required	string	Name in the indicated language.
releasesLocals.version optional	string	Version in the indicated language.
releasesLocals.languageId required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. 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
artistLocals.name required	string	Name in the indicated language.
artistLocals.languageId required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource.
contributors required	array of objects	Additional key artists who should be given top level credit. Do not provide individual band member names. For example, “The Beatles” and, not John Lennon, Paul McCartney, George Harrison and Ringo Starr. Parameter is mandatory even if the array is empty. 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.
contributors.contributorId optional	GUID	ID for an existing contributor. Not relevant for new releases. Should be provided when editing existing releases.
contributors.roleId required	integer	The artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles. The “primary artist” role (roleId 49) should only be used to name additional primary artists. The first (or only) primary artist should only be indicated as the main artist with the artistName parameter. Any role with priority 5 or from contributorRoleGroupId = 4 should not be used in the contributors array, except in the case of classical music where the “composer” role (roleId 2) is required. Priority 5 or contributorRoleGroupId = 4 indicates the role is a publishing role, which should be provided provided per track in the composerContentsDTO array. 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.
contributors.artist required	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
version optional	string	Title version. For example, Remastered or Deluxe edition. Typically omitted unless the release is a new version of a previously released release.
copyrightP required	string	The product copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The product copyright holder is the person or entity that owns the exclusive rights to the complete product, including both sound recording and artwork.
copyrightC required	string	The sound recording copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The sound recording copyright holder is the person or entity that owns the exclusive rights to the sound recording.
hasRecordLabel optional	boolean	true - The release has a record label. (See additional required parameters below). false - The release does not have a record label. (Default) If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release. If the primary artist for the release is new or is an existing artist not associated with a label, a new label will be created and assigned to the release with the same name as the artist.
labelName optional	string	Should never be provided when hasRecordLabel is false. When provided without labelId, tries to find an existing label with the same name (case-insensitive). If no such label is found, creates a new label and assigns it to the release. When provided with labelId, the labelName is ignored. The label associated with the labelId will be assigned to the release and the name of the label will not be updated. If neither a labelId nor a labelName are provided and hasRecordLabel is true: If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release. If the primary artist for the release is new or is an existing artist not associated with a label, throws an exception.
labelId optional	integer	ID for an existing label to assign to the release. Should never be provided when hasRecordLabel is false. If neither a labelId nor a labelName are provided and hasRecordLabel is true: If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release. If the primary artist for the release is new or is an existing artist not associated with a label, throws an exception.
artistAppleId required	string	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 required	string	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.
previouslyReleased optional	boolean	true - The release has been released previously to being added to the Revelator system. When true, upc and releaseDate are required parameters. You should not manually update this parameter after distributing the release in the Revelator system. false - The release has not been released previously. (Default)
upc optional	integer	UPC/EAN/JAN code for the release. The UPC is a unique code that every release must have. The system will automatically generate one upon distribution (free of charge) if you omit this parameter. You should never generate a new UPC for a release that already has one. Required when previouslyReleased is true. The value needs to be unique across the system
releaseDate optional	string	Official date the release was previously released in the ISO format YYYY-MM-DD Required when previouslyReleased is true; otherwise should not be provided. When distributing the release with the Revelator system, you should not manually update this parameter; you should only set the saleStartDate parameter in the distribution options endpoint. See Setting Distribution Options.
primaryMusicStyleId required	integer	ID for the release’s primary music style. Lookup music style IDs using the GET /common/lookup/musicstyles resource.
languageId required	integer	Language ID for the release’s meta data. This is not the language of the songs/lyrics, but the language of the information provided in this API request. Lookup up the languageId using the GET /common/lookup/languages resource. English is 1.
description optional	string	Release description.
tracks required	array of objects	Tracks for the release. Each object in the array represents a track. Unlike the behavior for most parameters, completely omitting the tracks parameter when editing an existing release will not remove all existing tracks from the release. Although tracks are not required when creating a release, they are required to distribute the release. See Track Object.
image optional	object	Cover image for the release. Although a cover image is not required when creating a release, it is required to distribute the release. Stores and services will reject images that do not conform to the following standards: Technical specifications: File format must be JPG Color space must be RGB Minimum dimensions of 1400x1400 pixels; 3000x3000 pixels recommended Must be a square image (width and height the same) May not contain more than 50 megapixels or be larger than 10 Mb Cannot be stretched, upscaled, or appear to be low-resolution Content: Information must match album title and artist name No website addresses, social media links or contact information No sexually explicit imagery Cannot be misleading by figuring a different artist’s name more prominently No third-party logo or trademarks without express written permission from the trademark holder 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.

Example

Request

curl -X POST 'http://api.revelator.com/content/release/save' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
-d '{
    "artistName": "Release_artist",
    "contributors": [],
    "copyrightC": "2018 companyC",
    "copyrightP": "2018 companyP",
    "hasRecordLabel": false,
    "previouslyReleased": false,
    "languageId": 1,
    "name": "Single",
    "primaryMusicStyleId": 60,
    "releasesLocals": [],
    "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "filename": "file123.jpg"
    },
    "tracks": [
        {
            "artistName": "TRACK_ARTIST",
            "languageId": 1,
            "name": "Single",
            "explicit": false,
            "wav": {
                "filename": "file123.wav",
                "fileId": "00000000-0000-0000-0000-000000000000"
            },
            "trackLength": 267,
            "sampleRate": 44100,
            "composerContentsDTO": [
                {
                    "composerName": "John Doe",
                    "rightsId": 1,
                    "roleId": 2,
                    "share": 100,
                    "composerImageId": "00000000-0000-0000-0000-000000000000"
                }
            ]
        }
    ]
}'

Artist Object

Parameter	Type	Description
name optional	string	Name of the artist. When provided without an artistId, tries to find an existing artist with the same name (case-insensitive). If no such artist is found, creates a new artist. When provided with an artistId, updates the name of the artist. 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 in the parent enterprise.
artistId optional	integer	ID for an existing artist. 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.
artistExternalIds optional	array of objects	External IDs for the artist for each store. Each supported store should have one or zero entries. These IDs are used by the stores to make sure that all of an artist’s content stays together. Each object in the array represents an external ID for the artist at a specific store. 0, null or no entry will result in different behavior for each store during distribution Apple Music (1): A new profile will be created during distribution Spotify (9): A new profile will be created when the release goes live SoundCloud (68): Soundclound will map the artist to a profile of their choosing or create a new profile if unsuccessful. Meta (309): Meta will map the artist to a profile of their choosing. New profile cannot be created automatically.
artistExternalIds.profileId required	string	External ID for the artist at the specified store. To find this ID go to the artist’s page at the store, and copy the numeric part of the URL For an artist not on the store, provide 0, null or omit this array entry. Behavior will differ depending on the store.
artistExternalIds.distributorStoreId required	string	Revelator ID for the store. Currently supported for: Apple Music - 1 Spotify - 9 Soundcloud - 68 Meta - 309
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
artistLocals.name required	string	Name in the indicated language.
artistLocals.languageId required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource.

File Object

Parameter	Type	Description
filename required	string	Name of the file, including the extension.
fileId required	string	The ID for a file that has already been uploaded to the Revelator server. See Uploading Files

Audio File Object

Used within the trackRecordingVersions.audioFiles array.

Parameter	Type	Description
audioId required	string	The ID for a file that has already been uploaded to the Revelator server. See Uploading Files
audioFilename required	string	Name of the audio file, including the extension.
fileFormat required	string	1 - WAV 2 - FLAC 3 - MP3

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. Note that you should not use the same trackId on more than one release. You should only provide an existing trackId in a case where you are editing an existing release or assigning a track that is not yet assigned to any release. In a case where the same track (same ISRC) is used on more than one release, you should create the track as new for the second release (generate a new trackId). 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 oneartist. 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 (case-insensitive). 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 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.
tracksLocals.name required	string	Name in the indicated language.
tracksLocals.version optional	string	Version in the indicated language.
tracksLocals.languageId required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. 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
artistLocals.name required	string	Name in the indicated language.
artistLocals.languageId required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. 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. For example, “The Beatles” and, not John Lennon, Paul McCartney, George Harrison and Ringo Starr. 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.
contributors.contributorId optional	GUID	ID for an existing contributor. Not relevant for new releases. Should be provided when editing existing releases.
contributors.roleId required	integer	The artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles. The “primary artist” role (roleId 49) should only be used to name additional primary artists. The first (or only) primary artist should only be indicated as the main artist with the artistName parameter. Any role with priority 5 or from contributorRoleGroupId = 4 should not be used in the contributors array, except in the case of classical music where the “composer” role (roleId 2) is required. Priority 5 or contributorRoleGroupId = 4 indicates the role is a publishing role, which should be provided provided per track in the composerContentsDTO array. 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.
contributors.artist required	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 required	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 required	boolean	Be sure that your user interface indicates the importance of properly identifying this content. Misidentifying this content can result in your distribution being disabled. 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 required	integer	One of the following: 1 - Original song 2 - Cover song 3 - Public domain song For detailed information, see Track Origin & Track Properties.
trackProperties required	array of integers	One or multiple of the following: 1 - None (If included, no other value should be provided) 2 - Remix 3 - Samples or Stock 4 - Mix or Compilation 5 - Alternate version 6 - Special Genre 7 - Non-Musical Content 8 - Includes AI For detailed information, see Track Origin & TrackProperties.
artistAppleId required	string	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 required	string	One of the following: For artists already on Spotify, existing Apple 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.
composerContentsDTO required	array of objects	A list of publishing contributors(composers) for the track .
composerContentsDTO.composerName optional	string	Name of the composer. When provided without composerId, tries to find an existing composer with the same name (case-insensitive). 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.
composerContentsDTO.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.
composerContentsDTO.rightsId required	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)
composerContentsDTO.roleId required	integer	A role associated with the composer. Look up roleIds with GET /common/lookup/contributorRoles. Only roles with priority = 5 or contributorRoleGroupId = 4 are relevant for composers.
composerContentsDTO.share optional	string	Share percentage for the composer. The total percentage for all composers must be 100%. Note that this has nothing to do with contract splits, and publisher royalties are never paid through the Revelator platform.
composerContentsDTO.publisherName optional	string	Name of the publisher to assign to the composer. Only relevant when rightsId is 2. When provided without an existing publisherId, tries to find an existing publisher with the same name (case-insensitive). If no such publisher is found, creates a new publisher. 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).
composerContentsDTO.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). *Set the publisherId to 0 (along with providing a publisherName) to create a new publisher whenever no existing publisher with the provided name exists. Omitting this parameter will cause the publisher (name and ID) to be null.
composerContentsDTO.composersLocals optional	array of objects	Composer name in different languages. If name or languageId are omitted, the object will be ignored.
composerContentsDTO.composersLocals.name optional	string	Name in the indicated language.
composerContentsDTO.composersLocals.version optional	string	Version in the indicated language.
composerContentsDTO.composersLocals.languageId optional	integer	Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource.
lyrics optional	string	Lyrics for the track. Note that not all stores accept lyrics.
isrc optional	string	This field is part of the old Track Recording model. See New track recording model for more information. 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).
wav optional	object	This field is part of the old Track Recording model. See New track recording model for more information. Audio file for the track in WAV format. 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. 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
trackRecordingVersions optional	array of objects	This field is part of the new Track Recording model. See New track recording model for more information. If provided, this list needs to have A mandatory stereo version (recordingVersionType - 1) An optional Dolby Atmos version (recordingVersionType - 2). Sample rate needs to be 48000 Hz The number of channels needs to be at least 3 The file size needs to be less than 2GB The length of the recording must match the length of the stereo version. The ISRCs must be different between the two versions. Once a Track Version is created, it cannot be removed (only edited, but even then limited)
trackRecordingVersions.recordingVersionType required	integer	Type of the track version. 1 - Stereo 2 - Dolby Atmos
trackRecordingVersions.isrc required	string	A valid ISRC code for the track version. If Dolby Atmos version exists, it’s ISRC cannot match the stereo version. These need to be unique. Leave as null if the ISRC should be generated automatically (during distribution).
trackRecordingVersions.audioFiles required	array of objects	When creating a new track, this array must contain a single object with a WAV (1) or a FLAC (2) fileFormat. If multiple objects are provided, only one will be used, where WAV has the priority over FLAC. if neither are provided the track will be created without an audio file. When editing an existing track: If the request is to replace the audio file - The list must contain only one object specifying the new audio file. (This only works for stereo files. Due to DSP restrictions, we DO NOT support updating Dolby Atmos files) If the request is to edit an unrelated field - The list must have the exact same values returned by the GET /content/track/{trackId} endpoint. See Audio File Object

New track recording model (Dolby Atmos Support)

With the release of support for Dolby Atmos, we have updated the track object adequately. The old model is going to remain supported with the goal of backwards compatibility; however, we strongly advise adapting to this new model (even if not utilizing Dolby Atmos).

---

New model (Supports Dolby Atmos)

Track object includes the following properties:

• trackRecordingVersions[]
  • isrc
  • recordingVersionType
  • trackRecordingVersions.audioFiles[] - audioFiles.audioId - audioFiles.audioFilename - audioFiles.fileFormat

---

Old model (Does not support Dolby Atmos)

Track object includes the following properties:

• isrc
• wav or flac

---

Refer to the track object table for coprehensive information on these fields

Uploading Files

All files must be uploaded before being associated with a track or a release. This goes for both audio and image assets.

POST /media/audio/upload

Uploads WAV or FLAC audio files.

Form Data

Form Field	Type	Description
file required	binary	The audio file to upload

Response

Field	Type	Description
fileId	string	The ID of the uploaded file that’s going to be used to reference it across the application.
filename	string	The filename of the uploaded file.

POST /media/audio/upload/wav

Uploads WAV audio files.

This endpoint has the same request, response, and requirements as POST /media/audio/upload. The file field in the Form Data should contain the WAV audio file.

POST /media/audio/upload/flac

Uploads FLAC audio files.

This endpoint has the same request, response, and requirements as POST /media/audio/upload. The file field in the Form Data should contain the FLAC audio file.

POST /media/image/upload

Query Params

Parameter	Type	Description
cover optional	boolean	Is the image going to be used as a cover art

Form Data

Form Field	Type	Description
file required	binary	The image file to upload

Response

fileId - string

POST /media/audio/pullexternal/wav

An alternative way to upload files. As long as those are publicly available on the web.

This might prove useful if you don’t want to handle the file upload yourself or already have the asset uploaded and accessible elsewhere.

Request Body

Parameter	Type	Description
externalUrl required	string	A valid URL to a publicly available audio file.
filename required	string	The name of the file

Response

Field	Type	Description
fileId	string	The ID of the uploaded file that’s going to be used to reference it across the application.
filename	string	The filename of the uploaded file.

Retrieving Releases

Use the following endpoints to retrieve release data.

GET /content/release/all

Retrieves list of all releases the user has permissions to view.

GET /content/release/all/summary

Retrieves a summary of all releases the user has permissions to view.

GET /content/release/{releaseId}

Retrieves the release with the releaseId specified in the URL path.

Adding/Editing Artists

An artist is a metadata entity that is referenced in assets (releases and tracks).

POST /artists

Creates new or edits existing artists in the account associated with the access token.

For Child Account implementation models, you have the option to run requests in a child account while authenticated as a parent account user. See Running Requests in Child Accounts.

Request Body

Parameter	Type	Description
name optional	string	Name of the artist. When provided without an artistId, tries to find an existing artist with the same name (case-insensitive). If no such artist is found, creates a new artist. When provided with an artistId, updates the name of the artist. 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 in the parent enterprise.
artistId optional	integer	ID for an existing artist. 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.
artistExternalIds optional	array of objects	External IDs for the artist for each store. Each supported store should have one or zero entries. These IDs are used by the stores to make sure that all of an artist’s content stays together. Each object in the array represents an external ID for the artist at a specific store. 0, null or no entry will result in different behavior for each store during distribution Apple Music (1): A new profile will be created during distribution Spotify (9): A new profile will be created when the release goes live SoundCloud (68): Soundclound will map the artist to a profile of their choosing or create a new profile if unsuccessful. Meta (309): Meta will map the artist to a profile of their choosing. New profile cannot be created automatically.
artistExternalIds.profileId required	string	External ID for the artist at the specified store. To find this ID go to the artist’s page at the store, and copy the numeric part of the URL For an artist not on the store, provide 0, null or omit this array entry. Behavior will differ depending on the store.
artistExternalIds.distributorStoreId required	string	Revelator ID for the store. Currently supported for: Apple Music - 1 Spotify - 9 Soundcloud - 68 Meta - 309
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
artistLocals.name required	string	Name in the indicated language.
artistLocals.languageId required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource.
image optional	object	The image representing the artist. See File Object.
additionalContacts optional	array of objects	Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section.
activeFromDate optional	string	The specific date when the artist began their activity. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SS).
activeToDate optional	string	The specific date when the artist ended their activity (or null if still active). ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SS).
firstName optional	string	Legal first name of the artist. Must consist only of Unicode letters, hyphens (-), single quotes (’), or dots (.). Must have a total length between 1 and 100 characters (inclusive).
middleName optional	string	Legal middle name(s) of the artist.
lastName optional	string	Legal last name of the artist. Must consist only of Unicode letters, hyphens (-), single quotes (’), or dots (.). Must have a total length between 1 and 100 characters (inclusive).
isni optional	string	The International Standard Name Identifier (ISNI) for the artist. Must be exactly 16 alphanumeric characters, where the last character can also be ‘X’.
artistLabels optional	array of objects	An array of objects, each representing an association with a Label. See nested fields below for structure and requirements.
artistLabels.labelId required	integer	The ID of an existing Label to associate with the artist.
artistLabels.contractStartYear required	string	The start date of the contract between the artist and this label. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ).
artistLabels.contractEndYear optional	string	The end date of the contract between the artist and this label. If provided, must be after contractStartYear. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ).

Retrieving Artists

Use the following endpoints to retrieve artist data.

For Child Account implementation models, you have the option to run requests in a child account while authenticated as a parent account user. See Running Requests in Child Accounts.

GET /artists

Retrieves list of all artists in the account.

Query params

Parameter	Type	Description
labels optional	array	An array of label IDs to filter artists associated with any of the specified labels.
name optional	string	Name of artist, case-sensitive, exact match.
isni optional	string	Filters artists by their International Standard Name Identifier (ISNI).
contributorGroupId optional	integer	Filters artists who have contributed to tracks/releases using a role that belongs to the specified Contributor Role Group ID. Refer to /common/lookup/ContributorRolesGroups for available group IDs.

Example

Request

curl -X GET -H 'Accept: text/plain'\
'http://api.revelator.com/artists?labels=labelA&labels=labelB'

Response

{
  "totalItemsCount": 0,
  "pageNumber": 0,
  "pageSize": 0,
  "items": [
    {
      "artistId": 0,
      "name": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "isni": "string",
      "releasesCount": 0,
      "tracksCount": 0,
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-12T12:38:18.124Z"
      }
    }
  ],
  "additionalCounters": {}
}

GET /artists/summary

Retrieves a summary of all artists in the account.

GET /artists/{artistId}

Retrieves the artist with the artistId specified in the URL path.

Query params

Parameter	Type	Description
labels optional	array	One or more labels associated with artists
name optional	string	Name of artist

GET /content/artist/all

Retrieves paginated list of all artists in the account.

Query params

Parameter	Type	Description
labels optional	array	An array of label IDs to filter artists associated with any of the specified labels.
name optional	string	Filters artists by name (case-insensitive, exact match).
fromDate optional	date-time	Filters for artists created on or after the provided date. Expected format: YYYY-MM-DDTHH:MM:SS (e.g., ISO 8601 without timezone).
toDate optional	date-time	Filters for artists created on or before the provided date. Expected format: YYYY-MM-DDTHH:MM:SS (e.g., ISO 8601 without timezone).
musicStyles optional	array	An array of music style IDs to filter artists associated with any of the specified music styles.
isni optional	string	Filters artists by their International Standard Name Identifier (ISNI).
contributorGroupId optional	integer	Filters artists who have contributed to tracks/releases using a role that belongs to the specified Contributor Role Group ID. Refer to /common/lookup/ContributorRolesGroups for available group IDs.
pageNumber optional	integer	The page number of the results to retrieve. Default is 1.
pageSize optional	integer	The number of items per page. Default is a system-defined value. Requires pageNumber query parameter to work properly.
orderByProperty optional	string	The property to sort the results by. Available options: - artistId - isni - name - firstName - middleName - lastname
orderByDescending optional	boolean	If true or omitted, orders the results in descending order. If false, orders in ascending order.
searchText optional	string	Allows to search by client’s name.

Example

Request

curl -X GET -H 'Accept: text/plain'\
'http://api.revelator.com/content/artists/all?orderByProperty=middleName&pageSize=10&pageNumber=1'

Response

{
  "totalItemsCount": 0,
  "pageNumber": 0,
  "pageSize": 0,
  "items": [
    {
      "additionalContacts": [
        {
          "contactId": 0,
          "name": "string",
          "currencyCode": "string",
          "phone": "string",
          "email": "string",
          "address": "string",
          "address2": "string",
          "zipcode": "string",
          "countryId": 0,
          "imageId": "00000000-0000-0000-0000-000000000000",
          "image": {
            "fileId": "00000000-0000-0000-0000-000000000000",
            "isTemp": true,
            "filename": "string",
            "externalUrl": "string",
            "lastUpdateDate": "2025-06-12T12:38:18.507Z"
          },
          "isActive": true,
          "labelId": 0,
          "publisherId": 0,
          "artistId": 0,
          "city": "string",
          "state": "string",
          "location": "string",
          "contactRoleId": 0
        }
      ],
      "musicStyles": [
        {
          "musicStyleId": 0,
          "name": "string"
        }
      ],
      "creationDate": "2025-06-12T12:38:18.508Z",
      "artistId": 0,
      "name": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "isni": "string",
      "releasesCount": 0,
      "tracksCount": 0,
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-12T12:38:18.508Z"
      }
    }
  ],
  "additionalCounters": {}
}

Managing External Artist IDs

Some DSPs share their artist IDs with us, allowing us to tightly couple our artists with theirs. This enables us to avoid situations where two different artists with the same name are merged or a single artist’s catalog is split between two or more profiles.

If an artist is already on the DSP, we require you to provide this ID when creating releases for the artist. If an artist is not already on the DSP, we require you to indicate that we should generate an ID for the artist when (if ever) the artist is distributed to the DSP.

Empty external IDs

Always provide a profile if it exists for the artist. However, the profileId may be left empty.

Each DSP has different behavior when an artist’s profileId is not provided (0, null or no entry in the artistExternalIds array).

• Apple Music (1): The profile will be generated during distribution.
• Spotify (9): The profile will be generated when a release goes live.
• SoundCloud (68): Soundclound will map the artist to a profile of their choosing, or create a new profile if unsuccessful. Please contact Support if you notice your release mapped to the wrong page.
• Meta (309): Meta will map the artist to an existing profile. Please contact Support if you notice your Release mapped to the wrong page. New profile cannot be created automatically.

Distributing additional releases for artists with new IDs

You must retrieve newly generated IDs immediately before distributing additional releases for an artist.

1. Specify the Revelator artistId parameter in the new release to ensure that the same Revelator artist is being assigned.
2. Immediately before distributing the new release, retrieve the ID with the GET /content/artist/all or GET /content/artist/{Id} endpoint. The response will include the profileId for each DSP with an existing value. See Artist Object.

3. Specify the current values for the external IDs in the release metadata.
4. Distribute the new release.

Adding/Editing Publishers

A publisher is a metadata entity that is referenced in assets (releases and tracks).

POST /content/publisher/save

Creates a new publisher or updates an existing one. The target enterprise for the operation can be specified if the authenticated user has appropriate parent/child account permissions.

Request Body

Parameter	Type	Description
publisherId optional	Integer	ID for an existing publisher. Required when editing publisher, should be ommited or set to 0 when creating new publisher.
name required	string	Full name of the publisher.
ipiCae optional	string	IPI (Interested Parties Information) - CAE (Composer, Author, and Publisher) number. Exactly 9 digits (IPI) or 11 digits (CAE). Unique across publishers and composers (writers) in the same tenant if present. Used to identify publishers across rights organizations.
image optional	object	The image representing the publisher. See File Object.
image.fileId required	string	The ID of the previously uploaded file. Required when image object is present.
image.filename required	string	Name of the previously uploaded file with extension.
proAffiliations optional	array of objects	A list detailing the Performance Rights Organizations (PROs) affiliations.
proAffiliations.proId required	integer	Our internal ID linking to the mechanicalPros entity.
proAffiliations.memberId required	string	Unique ID issued by PRO. Unique across composers and publishers for the same tenant.
additionalContacts optional	array of objects	Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section.
website optional	string	Publisher’s website.
countryId optional	integer	Country where this publisher administers publishing rights and collects royalties.
enterpriseId optional	integer	Specifies the target enterprise ID for the publisher. Usage Context: Primarily used by parent enterprise users to manage publishers within one of their child enterprises. During Creation (when publisherId is omitted or 0): If the authenticated user is from a child enterprise: This field is optional. If omitted, the publisher is created in the user’s own enterprise. If provided, it must match the user’s enterprise ID. If the authenticated user is from a parent enterprise: This field is required to specify the target child enterprise for creation. Omitting it will result in an error. During Update (when a valid publisherId is provided): If the authenticated user is from a child enterprise: This field is generally ignored, as the update targets the specific publisher ID which already exists within their enterprise. If the authenticated user is from a parent enterprise: This field is ignored. The update targets the publisher identified by publisherId regardless of which child enterprise it belongs to (assuming the parent has access).

Example

Request

curl -X POST 'http://api.revelator.com/content/publisher/save' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
-d '{
  "publisherId": 0,
  "name": "Example Publisher",
  "ipiCae": "0000000111",
  "image": {
    "fileId": "00000000-0000-0000-a7d1-aaab06776049",
    "filename": "photo.jpg"
  },
  "proAffiliations": [],
  "additionalContacts": [
    {
        "contactId": 796718
    },
    {
        "name": "Booking Manager",
        "email": "[email protected]",
        "contactRoleId": 5
    }
  ],
  "website": "https://hello.com",
  "countryId": 875
}'

Retrieving Publishers

Use the following endpoints to retrieve publisher data.

GET /content/publisher/all

Retrieves a paginated list of all publishers in the account, with options for sorting and searching.

Query params

Parameter	Type	Description
pageNumber optional	integer	The page number of the results to retrieve. Default is 1.
pageSize optional	integer	The number of items to return per page. Default is 24. Requires pageNumber query parameter to work properly.
orderByProperty optional	string	The property to sort the results by. Available options: name publisherId ipiCae creationDate
orderByDescending optional	boolean	If false, orders the results in ascending order. If true or omitted, orders in descending order.
searchText optional	string	A search term to filter publishers by name. The search is case-insensitive.

Example

Request

curl -X GET 'http://api.revelator.com/content/publisher/all?pageNumber=1&pageSize=10&orderByProperty=name&orderByDescending=true'

Response

{
    "totalItemsCount": 24,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "publisherId": 1,
            "name": "Example Publisher",
            "ipiCae": "11111111111",
            "image": {
                "fileId": "00000000-0000-0000-0000-00000000",
                "isTemp": false,
                "filename": "photo.jpg",
                "externalUrl": null,
                "lastUpdateDate": "2032-04-14T14:12:37.097"
            },
            "proAffiliations": [],
            "additionalContacts": [],
            "worksCount": 0,
            "creationDate": "2020-05-23T19:06:44",
            "website": null,
            "countryId": 875
        },
        {
            "publisherId": 2,
            "name": "Example Publisher 2",
            "ipiCae": null,
            "image": null,
            "proAffiliations": [],
            "additionalContacts": [],
            "worksCount": 17,
            "creationDate": "2032-10-17T05:59:42",
            "website": "https://example.com",
            "countryId": 443
        },
    ],
    "additionalCounters": null
}

GET /content/publisher/all/summary

Retrieves a summarized list of publishers. Allows for searching and limiting results.

Query params

Parameter	Type	Description
query optional	string	A search term to filter publishers by name. The search is case-insensitive.
limit optional	integer	The maximum number of summary items to return.

Example

Request

curl -X GET 'http://api.revelator.com/content/publisher/all/summary?query=Publi&limit=1'

Response

[
    {
        "publisherId": 1111,
        "name": "Publisher",
        "ipiCae": null,
        "image": null,
        "proAffiliations": [],
        "additionalContacts": [],
        "worksCount": 10,
        "creationDate": "2021-10-06T10:46:16.483",
        "website": null,
        "countryId": 875
    }
]

GET /content/publisher/{publisherId}

Retrieves detailed information for a specific publisher by its publisherId.

Path Parameters

Parameter	Type	Description
publisherId	integer	The unique ID of the publisher to retrieve.

Example

Request

curl -X GET 'http://api.revelator.com/content/publisher/12345'

Response

{
    "publisherId": 12345,
    "name": "Publisher Name",
    "ipiCae": "111111111",
    "image": null,
    "proAffiliations": [],
    "additionalContacts": [],
    "worksCount": 0,
    "creationDate": "2020-05-23T19:06:44",
    "website": null,
    "countryId": 875
}

Adding/Editing Composers

A composer(writer) is a metadata entity that is referenced in assets (releases and tracks).

POST /content/composer/save

Creates a new composer or updates an existing one. The target enterprise for the operation can be specified if the authenticated user has appropriate parent/child account permissions.

Request Body

Parameter	Type	Description
composerId optional	Integer	ID for an existing composer. Required when editing composer, should be ommited or set to 0 when creating new composer.
name required	string	Composer’s full legal name exactly as shown on official paperwork (e.g., contracts, copyright registrations).
isni optional	string	The International Standard Name Identifier (ISNI) for the artist. Must be exactly 16 alphanumeric characters, where the last character can also be ‘X’.
ipiCae optional	string	IPI (Interested Parties Information) - CAE (Composer, Author, and Publisher) number. Exactly 9 digits (IPI) or 11 digits (CAE). Unique across publishers and composers (writers) in the same tenant if present. Used to identify publishers across rights organizations.
biography optional	string	Composers’s biography.
countryOfResidenceId optional	integer	The country in which this contributor officially resides. Used for legal and payout requirements.
composersLocals optional	array of objects	A list of Composer’s name in different languages.
composersLocals.name required	string	Composer’s name in the indicated language.
composersLocals.languageId required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. Updates to local names are based on this field. If you don’t inclde object with specified languageId entry with it will be deleted.
image optional	object	The image representing the publisher. See File Object.
image.fileId required	string	The ID of the previously uploaded file. Required when image object is present.
image.filename required	string	Name of the previously uploaded file with extension.
proAffiliations optional	array of objects	A list detailing the Performance Rights Organizations (PROs) affiliations.
proAffiliations.proId required	integer	Our internal ID linking to the mechanicalPros entity.
proAffiliations.memberId required	string	Unique ID issued by PRO. Unique across composers and publishers for the same tenant.
additionalContacts optional	array of objects	Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section.
enterpriseId optional	integer	Specifies the target enterprise ID for the composer. Usage Context: Primarily used by parent enterprise users to manage composers within one of their child enterprises. During Creation (when composerId is omitted or 0): If the authenticated user is from a child enterprise: This field is optional. If omitted, the composer is created in the user’s own enterprise. If provided, it must match the user’s enterprise ID. If the authenticated user is from a parent enterprise: This field is required to specify the target child enterprise for creation. Omitting it will result in an error. During Update (when a valid composerId is provided): If the authenticated user is from a child enterprise: This field is generally ignored, as the update targets the specific composer ID which already exists within their enterprise. If the authenticated user is from a parent enterprise: This field is ignored. The update targets the composer identified by composerId regardless of which child enterprise it belongs to (assuming the parent has access).

Example

Request

curl -X POST 'http://api.revelator.com/content/publisher/save' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
-d '{
  "composerId": 0,
  "name": "Example Composer",
  "isni": "123456789098765X",
  "ipiCae": "00000001111",
  "biography": "Composer's biography",
  "countryOfResidenceId": 244,
  "composersLocals":[
    {
      "name": "Local Composer Name",
      "languageId": 4
    }
  ],
  "image": {
    "fileId": "00000000-0000-0000-a7d1-aaab06776049",
    "filename": "photo.jpg"
  },
  "proAffiliations": [],
  "additionalContacts": [
    {
        "contactId": 796718
    },
    {
        "name": "Booking Manager",
        "email": "[email protected]",
        "contactRoleId": 5
    }
  ]
}'

Response

{
  "composerId": 0,
  "name": "string",
  "isni": "string",
  "ipiCae": "string",
  "biography": "string",
  "countryOfResidenceId": 0,
  "image": {
    "fileId": "00000000-0000-0000-0000-000000000000",
    "isTemp": true,
    "filename": "string",
    "externalUrl": "string",
    "lastUpdateDate": "2025-06-13T06:52:11.114Z"
  },
  "worksCount": 0,
  "contributorRoleIds": [
    0
  ],
  "creationDate": "2025-06-13T06:52:11.114Z",
  "publishersCount": 0,
  "composersLocals": [
    {
      "composerId": 0,
      "name": "string",
      "languageId": 0
    }
  ],
  "additionalContacts": [
    {
      "contactId": 0,
      "name": "string",
      "currencyCode": "string",
      "phone": "string",
      "email": "string",
      "address": "string",
      "address2": "string",
      "zipcode": "string",
      "countryId": 0,
      "imageId": "00000000-0000-0000-0000-000000000000",
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-13T06:52:11.114Z"
      },
      "isActive": true,
      "labelId": 0,
      "publisherId": 0,
      "artistId": 0,
      "city": "string",
      "state": "string",
      "location": "string",
      "contactRoleId": 0
    }
  ],
  "proAffiliations": [
    {
      "proId": 0,
      "memberId": "string"
    }
  ]
}

Retrieving Composers

Use the following endpoints to retrieve composer data.

GET /content/composer/all

Retrieves a paginated list of all composers in the account, with options for sorting and searching.

Query params

Parameter	Type	Description
pageNumber optional	integer	The page number of the results to retrieve. Default is 1.
pageSize optional	integer	The number of items to return per page.
orderByProperty optional	string	The property to sort the results by. Available options: name composerId ipiCae isni creationDate email
orderByDescending optional	boolean	If false, orders the results in ascending order. If true or omitted, orders in descending order.
searchText optional	string	A search term to filter composer by name. The search is case-insensitive.

Example

Request

curl -X GET 'http://api.revelator.com/content/composer/all?pageNumber=1&pageSize=10&orderByProperty=name&orderByDescending=true'

Response

{
  "totalItemsCount": 0,
  "pageNumber": 0,
  "pageSize": 0,
  "items": [
    {
      "composerId": 0,
      "name": "string",
      "isni": "string",
      "ipiCae": "string",
      "biography": "string",
      "countryOfResidenceId": 0,
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-13T06:52:11.111Z"
      },
      "worksCount": 0,
      "contributorRoleIds": [
        0
      ],
      "creationDate": "2025-06-13T06:52:11.111Z",
      "publishersCount": 0,
      "composersLocals": [
        {
          "composerId": 0,
          "name": "string",
          "languageId": 0
        }
      ],
      "additionalContacts": [
        {
          "contactId": 0,
          "name": "string",
          "currencyCode": "string",
          "phone": "string",
          "email": "string",
          "address": "string",
          "address2": "string",
          "zipcode": "string",
          "countryId": 0,
          "imageId": "00000000-0000-0000-0000-000000000000",
          "image": {
            "fileId": "00000000-0000-0000-0000-000000000000",
            "isTemp": true,
            "filename": "string",
            "externalUrl": "string",
            "lastUpdateDate": "2025-06-13T06:52:11.111Z"
          },
          "isActive": true,
          "labelId": 0,
          "publisherId": 0,
          "artistId": 0,
          "city": "string",
          "state": "string",
          "location": "string",
          "contactRoleId": 0
        }
      ],
      "proAffiliations": [
        {
          "proId": 0,
          "memberId": "string"
        }
      ]
    }
  ],
  "additionalCounters": {}
}

GET /content/composer/all/summary

Retrieves a summarized list of composers. Allows for searching and limiting results.

Query params

Parameter	Type	Description
query optional	string	A search term to filter composers by name. The search is case-insensitive.
limit optional	integer	The maximum number of summary items to return.
enterpriseId optional	integer	Used when executing from parent account to return composers from intended child account.

Example

Request

curl -X GET 'http://api.revelator.com/content/composer/all/summary?query=Test&limit=1&enterpriseId=12'

Response

[
  {
    "composerId": 0,
    "name": "string",
    "composersLocals": [
      {
        "composerId": 0,
        "name": "string",
        "languageId": 0
      }
    ],
    "imageId": "00000000-0000-0000-0000-000000000000"
  }
]

GET /content/composer/{composerId}

Retrieves detailed information for a specific composer by its composerId.

Path Parameters

Parameter	Type	Description
composerId	integer	The unique ID of the composer to retrieve.

Example

Request

curl -X GET 'http://api.revelator.com/content/composer/12345'

Response

{
  "composerId": 0,
  "name": "string",
  "isni": "string",
  "ipiCae": "string",
  "biography": "string",
  "countryOfResidenceId": 0,
  "image": {
    "fileId": "00000000-0000-0000-0000-000000000000",
    "isTemp": true,
    "filename": "string",
    "externalUrl": "string",
    "lastUpdateDate": "2025-06-13T06:52:11.117Z"
  },
  "worksCount": 0,
  "contributorRoleIds": [
    0
  ],
  "creationDate": "2025-06-13T06:52:11.117Z",
  "publishersCount": 0,
  "composersLocals": [
    {
      "composerId": 0,
      "name": "string",
      "languageId": 0
    }
  ],
  "additionalContacts": [
    {
      "contactId": 0,
      "name": "string",
      "currencyCode": "string",
      "phone": "string",
      "email": "string",
      "address": "string",
      "address2": "string",
      "zipcode": "string",
      "countryId": 0,
      "imageId": "00000000-0000-0000-0000-000000000000",
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-13T06:52:11.117Z"
      },
      "isActive": true,
      "labelId": 0,
      "publisherId": 0,
      "artistId": 0,
      "city": "string",
      "state": "string",
      "location": "string",
      "contactRoleId": 0
    }
  ],
  "proAffiliations": [
    {
      "proId": 0,
      "memberId": "string"
    }
  ]
}

Adding/Editing Contacts

A Contact represents an individual or organization (e.g., a manager, booking agent, legal representative) that can be associated with various entities in the system like artists, labels, publishers, and composers.

POST /contact/create

Creates new contact in the account associated with the access token.

Request Body

Parameter	Type	Description
contactId optional	integer	An optional ID. If 0 or omitted, a new contact is created. If a valid contactId of an existing contact is provided, this endpoint will update all fields of that existing contact with the values provided in this request.
name optional	string	Name of the contact.
currencyCode optional	string	Currency code, can be checked using /common/lookup/currencies.
phone optional	string	Phone number of the contact.
email optional	string	Contact’s email address.
address optional	string	Address of the contact (Street, company name, etc.).
address2 optional	string	Address of the contact (Apartment, building, floor, etc.).
zipcode optional	string	Zip code.
countryId optional	integer	Country id, can be checked using /common/lookup/countries.
imageId optional	string	The ID for a file that has already been uploaded to the Revelator server. See Uploading Files
isActive optional	boolean	Indicates if contact is active, when omitted defaults to false
labelId optional	integer	ID of existing label. Can be used to assign contact the the label.
publisherId optional	integer	ID of existing publisher. Can be used to assign contact the the publisher.
artistId optional	integer	ID of existing artist. Can be used to assign contact the the artist.
city optional	string	City of the contact.
state optional	string	State/Province of the contact.
location optional	string	Location of the contact.

Example

Response

{
  "contactId": 67,
  "name": "John Doe",
  "currencyCode": "USD",
  "phone": "+1 123-456-789",
  "email": "[email protected]",
  "address": "string",
  "address2": "string",
  "zipcode": "string",
  "countryId": 244,
  "imageId": "00000000-0000-0000-0000-000000000000",
  "image": {
    "fileId": "00000000-0000-0000-0000-000000000000",
    "isTemp": true,
    "filename": "string",
    "externalUrl": "string",
    "lastUpdateDate": "2025-06-04T07:07:54.581Z"
  },
  "isActive": true,
  "labelId": null,
  "publisherId": null,
  "artistId": null,
  "city": "string",
  "state": "string",
  "location": null
}

POST /contact/update

Updates existing contact in the account associated with the access token. Updating affects only properties listed below. Rest of existing properties on contact will remain unchanged. If you want to update them you should use /contact/create and provide contactId.

Request Body

Parameter	Type	Description
contactId required	integer	ID for an existing contact.
name optional	string	Name of the contact.
phone optional	string	Phone number of the contact.
email optional	string	Contact’s email address.
address optional	string	Address of the contact (Street, company name, etc.).
address2 optional	string	Address of the contact (Apartment, building, floor, etc.).
countryId optional	integer	Country id, can be checked using /common/lookup/countries.

Example

Response

{
  "contactId": 67,
  "name": "John Doe",
  "currencyCode": "USD",
  "phone": "+1 123-456-789",
  "email": "[email protected]",
  "address": "string",
  "address2": "string",
  "zipcode": "string",
  "countryId": 244,
  "imageId": "00000000-0000-0000-0000-000000000000",
  "image": {
    "fileId": "00000000-0000-0000-0000-000000000000",
    "isTemp": true,
    "filename": "string",
    "externalUrl": "string",
    "lastUpdateDate": "2025-06-04T07:07:54.581Z"
  },
  "isActive": true,
  "labelId": null,
  "publisherId": null,
  "artistId": null,
  "city": "string",
  "state": "string",
  "location": null
}

Retrieving Contacts

Use the following endpoints to retrieve contact data.

GET /contact

Retrieves a single primary contact associated with a specific Enterprise, Label, Publisher, or Artist.

Query Params

Parameter	Type	Description
enterpriseId optional	integer	The ID of the Enterprise whose primary contact you want to retrieve.
labelId optional	integer	The ID of the Label whose primary contact you want to retrieve.
publisherId optional	integer	The ID of the Publisher whose primary contact you want to retrieve.
artistId optional	integer	The ID of the Artist whose primary contact you want to retrieve.

GET /contact/{id}

Used to retrieve specific existing contact.