Revelator Logo API
v1

Composers

A composer (also referred to as a writer) is a metadata entity representing an author of a musical work — a songwriter, lyricist, arranger, or similar contributor. Composers are the master identity referenced from tracks. The per-track credit — publishing type, contributor role, ownership share, and any associated publisher — is captured on the track itself, not on the composer record.

IPI/CAE Number

The ipiCae field holds the composer’s IPI (Interested Parties Information) or CAE (Composer, Author, and Publisher) number. It is used to identify the composer across performance and mechanical rights organizations.

The IPI/CAE number is a unique identifier assigned through the CISAC-managed IPI database by member societies to track rights holders in creative works.

To obtain or look up your number, join or log in to your local CISAC-member PRO (such as ASCAP, PRS, SACEM) or search the IPI database at cisac.org.

  • Suggested format: 9 digits (IPI) or 11 digits (CAE).

PRO Affiliations

Performance-Rights Organizations (PROs) are responsible for collecting and distributing royalties when music is performed, broadcast, or streamed.

Register each contributor with the appropriate PRO(s) in their region, then select those affiliations here so royalty earnings can be tracked and paid out correctly.

The proAffiliations array records the PROs a composer is affiliated with. Each entry pairs a proId (Revelator’s internal identifier for the PRO) with a memberId (the unique ID issued to the composer by that PRO). Available PROs and their corresponding proId values can be retrieved using GET /content/track/lookups on the V1.0 API.

The memberId must be unique across publishers and composers within the same organization. Attempting to save a composer with a memberId that is already in use by another publisher or composer in the organization returns a validation error.

Archiving Composers

A composer can only be archived when all of the following conditions are met:

  • The composer is not currently archived.
  • The composer is not assigned to any active (unarchived) release.
  • The composer is not assigned to any active (unarchived) track.

Composers that have been archived for more than 6 months can no longer be unarchived.

Create Composer

POST /catalog/v1/composers

Creates a new composer.

Request Body *

object
name * string
Composer's full legal name exactly as shown on official paperwork (e.g., contracts, copyright registrations). Emoji are not supported here, since composer names must reflect legal writer identities.
languageAndScriptCode string
Language and script code for the composer name (e.g., en-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
isni string
International Standard Name Identifier (ISNI) for the composer.
ipiCae string
IPI or CAE number for the composer. See the IPI/CAE Number section above for details.
biography string
Composer's biography.
countryOfResidenceId integer
The country in which this composer officially resides. Used for legal and payout requirements. Retrieved from GET /common/lookup/countries on the V1.0 API.
logoImageId string
File ID (GUID) of the composer's photo or logo image, uploaded via the Files API.
name * string
The composer's name in the specified language.
phoneticName string
Phonetic pronunciation of the name in this language.
languageAndScriptCode string
Language and script code for this localization entry (e.g., en-Latn). Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
languageId * integer
Language ID for this localization. Each language can be used only once in the array. Updates to local names are based on this field. Retrieved from GET /common/lookup/languages on the V1.0 API.
address string
Street address, line 1.
address2 string
Street address, line 2.
city string
City.
contactRoleId * integer
Role of this contact. Role IDs can be retrieved from GET /common/lookup/contactRoles on the V1.0 API.
countryId integer
Country ID. Retrieved from GET /common/lookup/countries on the V1.0 API.
email * string (email)
Contact's email address.
location string
General location description.
name * string
Contact's full name.
phone string
Contact's phone number.
state string
State or province.
zipCode string
Zip or postal code.
proId integer
Revelator's internal ID for the PRO. Retrieved from GET /content/track/lookups on the V1.0 API.
memberId string
Unique member ID issued by the PRO. Must be unique across publishers and composers within the same organization.
enterpriseId integer
The client under which the composer will be created. Defaults to the caller's client when using client permissions. Required when using organization permissions.

Responses

object
composerId integer
Unique identifier for the composer.
name string
Composer's full legal name.
languageAndScriptCode string | null
Language and script code for the composer name.
isni string | null
International Standard Name Identifier (ISNI) for the composer.
ipiCae string | null
IPI or CAE number for the composer.
biography string | null
Composer's biography.
countryOfResidenceId integer | null
The country in which this composer officially resides.
logoImageId string | null
File ID of the composer's photo or logo image.
roleId integer
Contributor role ID.
name string | null
Contributor role name.
enterpriseId integer | null
ID of the client that owns this composer.
tenantId integer
ID of the organization that owns this composer.
creationDate string (date-time)
UTC timestamp when the composer was created.
createdBy string
ID of the user who created the composer.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update. Set to the creation timestamp when the composer has never been explicitly updated.
lastUpdatedBy string | null
ID of the user credited with the most recent change. Set to the creating user at creation, then updated on each subsequent edit.
archivedAt string (date-time) | null
UTC timestamp when the composer was archived. null if the composer is active.
archivedBy string | null
ID of the user who archived the composer. null if the composer is active.
name * string
The composer's name in the specified language.
phoneticName string | null
Phonetic pronunciation of the name in this language.
languageAndScriptCode string | null
Language and script code for this localization entry.
languageId * integer
Language ID for this localization entry.
address string | null
Street address, line 1.
address2 string | null
Street address, line 2.
city string | null
City.
contactRoleId * integer
Role of this contact.
countryId integer | null
Country ID.
email * string (email)
Contact's email address.
location string | null
General location description.
name * string
Contact's full name.
phone string | null
Contact's phone number.
state string | null
State or province.
zipCode string | null
Zip or postal code.
proId integer
Revelator's internal ID for the PRO.
memberId string
Unique member ID issued by the PRO.
POST /catalog/v1/composers 
curl -X POST "https://platform.revelator.com/catalog/v1/composers" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Example Composer",
  "isni": "123456789098765X",
  "ipiCae": "00000001111",
  "biography": "Songwriter and producer based in Los Angeles.",
  "countryOfResidenceId": 244,
  "logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
  "locals": [
    { "name": "Local Composer Name", "languageId": 4 }
  ],
  "proAffiliations": [
    { "proId": 1, "memberId": "PRO-4471120" }
  ],
  "additionalContacts": [
    { "name": "Booking Manager", "email": "[email protected]", "contactRoleId": 5 }
  ],
  "enterpriseId": null
}'
Example response 200 
{
"composerId": 6601,
"name": "Example Composer",
"languageAndScriptCode": null,
"isni": "123456789098765X",
"ipiCae": "00000001111",
"biography": "Songwriter and producer based in Los Angeles.",
"countryOfResidenceId": 244,
"logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
"roles": [],
"locals": [
  { "name": "Local Composer Name", "phoneticName": null, "languageAndScriptCode": null, "languageId": 4 }
],
"proAffiliations": [
  { "proId": 1, "memberId": "PRO-4471120" }
],
"additionalContacts": [
  { "name": "Booking Manager", "email": "[email protected]", "contactRoleId": 5 }
],
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-01-10T12:03:43Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"lastUpdateDate": "2026-01-10T12:03:43Z",
"lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"archivedAt": null,
"archivedBy": null
}

Get Composer

GET /catalog/v1/composers/{composerId}

Retrieves a composer by its ID.

Path Parameters

Parameter Description
composerId * integer

The ID of the composer.

Responses

object
composerId integer
Unique identifier for the composer.
name string
Composer's full legal name.
languageAndScriptCode string | null
Language and script code for the composer name.
isni string | null
International Standard Name Identifier (ISNI) for the composer.
ipiCae string | null
IPI or CAE number for the composer.
biography string | null
Composer's biography.
countryOfResidenceId integer | null
The country in which this composer officially resides.
logoImageId string | null
File ID of the composer's photo or logo image.
roleId integer
Contributor role ID.
name string | null
Contributor role name.
enterpriseId integer | null
ID of the client that owns this composer.
tenantId integer
ID of the organization that owns this composer.
creationDate string (date-time)
UTC timestamp when the composer was created.
createdBy string
ID of the user who created the composer.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update. Set to the creation timestamp when the composer has never been explicitly updated.
lastUpdatedBy string | null
ID of the user credited with the most recent change. Set to the creating user at creation, then updated on each subsequent edit.
archivedAt string (date-time) | null
UTC timestamp when the composer was archived. null if the composer is active.
archivedBy string | null
ID of the user who archived the composer. null if the composer is active.
name * string
The composer's name in the specified language.
phoneticName string | null
Phonetic pronunciation of the name in this language.
languageAndScriptCode string | null
Language and script code for this localization entry.
languageId * integer
Language ID for this localization entry.
address string | null
Street address, line 1.
address2 string | null
Street address, line 2.
city string | null
City.
contactRoleId * integer
Role of this contact.
countryId integer | null
Country ID.
email * string (email)
Contact's email address.
location string | null
General location description.
name * string
Contact's full name.
phone string | null
Contact's phone number.
state string | null
State or province.
zipCode string | null
Zip or postal code.
proId integer
Revelator's internal ID for the PRO.
memberId string
Unique member ID issued by the PRO.
GET /catalog/v1/composers/{composerId} 
curl -X GET "https://platform.revelator.com/catalog/v1/composers/6601" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"composerId": 6601,
"name": "Example Composer",
"languageAndScriptCode": null,
"isni": "123456789098765X",
"ipiCae": "00000001111",
"biography": "Songwriter and producer based in Los Angeles.",
"countryOfResidenceId": 244,
"logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
"roles": [
  { "roleId": 2, "name": "Composer" }
],
"locals": [
  { "name": "Local Composer Name", "phoneticName": null, "languageAndScriptCode": null, "languageId": 4 }
],
"proAffiliations": [
  { "proId": 1, "memberId": "PRO-4471120" }
],
"additionalContacts": [
  { "name": "Booking Manager", "email": "[email protected]", "contactRoleId": 5 }
],
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-01-10T12:03:43Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"lastUpdateDate": "2026-02-01T08:20:10Z",
"lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"archivedAt": null,
"archivedBy": null
}

List Composers

GET /catalog/v1/composers

Returns a paginated list of composers based on filters and sorting options.

Query Parameters

Parameter Description
archived boolean

Filter by archive state (true for archived, false for active).
archivedDateFrom string (date-time)

Include composers archived on or after this UTC date-time.
archivedDateTo string (date-time)

Include composers archived on or before this UTC date-time.
creationDateFrom string (date-time)

Include composers created on or after this UTC date-time.
creationDateTo string (date-time)

Include composers created on or before this UTC date-time.
lastUpdateDateFrom string (date-time)

Include composers updated on or after this UTC date-time.
lastUpdateDateTo string (date-time)

Include composers updated on or before this UTC date-time.
searchText string

Free-text search applied to composer name.
publisherIds integer[]

Filter to composers with at least one track credit associated with the given publisher IDs. Maximum 100 IDs per request.
enterpriseIds integer[]

Filter by one or more client IDs. Maximum 100 IDs per request.
pageNumber integer

Page number for paginated results.
pageSize integer

Number of items per page. Maximum 204.
orderByProperty string

Property name used for sorting.

Examples: composerId, name, creationDate
orderByDescending boolean

Set to true for descending order, false for ascending.

Responses

object
pageNumber integer
Current page number.
pageSize integer
Number of items per page.
totalItemsCount integer
Total number of composers matching the filters.
totalPagesCount number
Total number of pages.
composerId integer
Unique identifier for the composer.
tenantId integer
ID of the organization that owns this composer.
enterpriseId integer
ID of the client that owns this composer.
name string | null
Composer's full legal name.
logoImageId string | null
File ID of the composer's photo or logo image.
isni string | null
International Standard Name Identifier (ISNI) for the composer.
ipiCae string | null
IPI or CAE number for the composer.
countryOfResidenceId integer | null
The country in which this composer officially resides.
creationDate string (date-time)
UTC timestamp when the composer was created.
createdBy string | null
ID of the user who created the composer.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update. Set to the creation timestamp when the composer has never been explicitly updated.
lastUpdatedBy string | null
ID of the user credited with the most recent change. Set to the creating user at creation, then updated on each subsequent edit.
archivedAt string (date-time) | null
UTC timestamp when the composer was archived. null if the composer is active.
archivedBy string | null
ID of the user who archived the composer. null if the composer is active.
roleId integer
Contributor role ID.
name string | null
Contributor role name.
GET /catalog/v1/composers 
curl -X GET "https://platform.revelator.com/catalog/v1/composers?pageNumber=1&pageSize=20&orderByProperty=name&orderByDescending=false" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"pageNumber": 1,
"pageSize": 20,
"totalItemsCount": 1,
"totalPagesCount": 1,
"items": [
  {
    "composerId": 6601,
    "tenantId": 2001,
    "enterpriseId": 3001,
    "name": "Example Composer",
    "logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
    "isni": "123456789098765X",
    "ipiCae": "00000001111",
    "countryOfResidenceId": 244,
    "roles": [
      { "roleId": 2, "name": "Composer" }
    ],
    "creationDate": "2026-01-10T12:03:43Z",
    "createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
    "lastUpdateDate": "2026-02-01T08:20:10Z",
    "lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
    "archivedAt": null,
    "archivedBy": null
  }
]
}

Update Composer

PUT /catalog/v1/composers/{composerId}

Updates an existing composer by its ID.

Path Parameters

Parameter Description
composerId * integer

The ID of the composer to update.

Request Body *

object
name string
Composer's full legal name exactly as shown on official paperwork (e.g., contracts, copyright registrations). Emoji are not supported here, since composer names must reflect legal writer identities.
languageAndScriptCode string
Language and script code for the composer name (e.g., en-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
isni string
International Standard Name Identifier (ISNI) for the composer.
ipiCae string
IPI or CAE number for the composer. See the IPI/CAE Number section above for details.
biography string
Composer's biography.
countryOfResidenceId integer
The country in which this composer officially resides. Used for legal and payout requirements. Retrieved from GET /common/lookup/countries on the V1.0 API.
logoImageId string
File ID (GUID) of the composer's photo or logo image, uploaded via the Files API.
name * string
The composer's name in the specified language.
phoneticName string
Phonetic pronunciation of the name in this language.
languageAndScriptCode string
Language and script code for this localization entry (e.g., en-Latn). Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API.
languageId * integer
Language ID for this localization. Each language can be used only once in the array. Updates to local names are based on this field. Retrieved from GET /common/lookup/languages on the V1.0 API.
address string
Street address, line 1.
address2 string
Street address, line 2.
city string
City.
contactRoleId * integer
Role of this contact. Retrieved from GET /common/lookup/contactRoles on the V1.0 API.
countryId integer
Country ID. Retrieved from GET /common/lookup/countries on the V1.0 API.
email * string (email)
Contact's email address.
location string
General location description.
name * string
Contact's full name.
phone string
Contact's phone number.
state string
State or province.
zipCode string
Zip or postal code.
proId integer
Revelator's internal ID for the PRO. Retrieved from GET /content/track/lookups on the V1.0 API.
memberId string
Unique member ID issued by the PRO. Must be unique across publishers and composers within the same organization.

Responses

object
composerId integer
Unique identifier for the composer.
name string
Composer's full legal name.
languageAndScriptCode string | null
Language and script code for the composer name.
isni string | null
International Standard Name Identifier (ISNI) for the composer.
ipiCae string | null
IPI or CAE number for the composer.
biography string | null
Composer's biography.
countryOfResidenceId integer | null
The country in which this composer officially resides.
logoImageId string | null
File ID of the composer's photo or logo image.
roleId integer
Contributor role ID.
name string | null
Contributor role name.
enterpriseId integer | null
ID of the client that owns this composer.
tenantId integer
ID of the organization that owns this composer.
creationDate string (date-time)
UTC timestamp when the composer was created.
createdBy string
ID of the user who created the composer.
lastUpdateDate string (date-time) | null
UTC timestamp of the most recent update.
lastUpdatedBy string | null
ID of the user who last updated the composer.
archivedAt string (date-time) | null
UTC timestamp when the composer was archived. null if the composer is active.
archivedBy string | null
ID of the user who archived the composer. null if the composer is active.
name * string
The composer's name in the specified language.
phoneticName string | null
Phonetic pronunciation of the name in this language.
languageAndScriptCode string | null
Language and script code for this localization entry.
languageId * integer
Language ID for this localization entry.
address string | null
Street address, line 1.
address2 string | null
Street address, line 2.
city string | null
City.
contactRoleId * integer
Role of this contact.
countryId integer | null
Country ID.
email * string (email)
Contact's email address.
location string | null
General location description.
name * string
Contact's full name.
phone string | null
Contact's phone number.
state string | null
State or province.
zipCode string | null
Zip or postal code.
proId integer
Revelator's internal ID for the PRO.
memberId string
Unique member ID issued by the PRO.
PUT /catalog/v1/composers/{composerId} 
curl -X PUT "https://platform.revelator.com/catalog/v1/composers/6601" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Example Composer",
  "isni": "123456789098765X",
  "ipiCae": "00000001111",
  "biography": "Songwriter and producer based in Los Angeles. Now signed to a major publisher.",
  "countryOfResidenceId": 244,
  "logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
  "locals": [
    { "name": "Local Composer Name", "languageId": 4 }
  ],
  "proAffiliations": [
    { "proId": 1, "memberId": "PRO-4471120" }
  ],
  "additionalContacts": [
    { "name": "Booking Manager", "email": "[email protected]", "contactRoleId": 5 }
  ]
}'
Example response 200 
{
"composerId": 6601,
"name": "Example Composer",
"languageAndScriptCode": null,
"isni": "123456789098765X",
"ipiCae": "00000001111",
"biography": "Songwriter and producer based in Los Angeles. Now signed to a major publisher.",
"countryOfResidenceId": 244,
"logoImageId": "a1b2c3d4-0000-4e5f-a678-426614174000",
"roles": [
  { "roleId": 2, "name": "Composer" }
],
"locals": [
  { "name": "Local Composer Name", "phoneticName": null, "languageAndScriptCode": null, "languageId": 4 }
],
"proAffiliations": [
  { "proId": 1, "memberId": "PRO-4471120" }
],
"additionalContacts": [
  { "name": "Booking Manager", "email": "[email protected]", "contactRoleId": 5 }
],
"tenantId": 2001,
"enterpriseId": 3001,
"creationDate": "2026-01-10T12:03:43Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"lastUpdateDate": "2026-06-12T09:00:00Z",
"lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"archivedAt": null,
"archivedBy": null
}

Archive Composers

POST /catalog/v1/composers/archive

Archives composers in batch by composer IDs.

Request Body *

object
Batch archive request payload.
composerIds * integer[]
List of composer IDs to archive. Maximum 100 IDs per request.

Responses

object
id integer
Composer ID from the request.
succeeded boolean
Whether the archive operation succeeded for this composer.
code string
Error code.
Examples: General.NotFound, General.Validation
message string
Human-readable error message.
POST /catalog/v1/composers/archive 
curl -X POST "https://platform.revelator.com/catalog/v1/composers/archive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "composerIds": [6601, 6602]
}'
Example response 200 
{
"results": [
  {
    "id": 6601,
    "succeeded": true,
    "errors": null
  },
  {
    "id": 6602,
    "succeeded": true,
    "errors": null
  }
]
}

Unarchive Composers

POST /catalog/v1/composers/unarchive

Unarchives composers in batch by composer IDs. Composers archived for more than 6 months can no longer be unarchived.

Request Body *

object
Batch unarchive request payload.
composerIds * integer[]
List of composer IDs to unarchive. Maximum 100 IDs per request.

Responses

object
id integer
Composer ID from the request.
succeeded boolean
Whether the unarchive operation succeeded for this composer.
code string
Error code.
Examples: General.NotFound, General.Validation
message string
Human-readable error message.
POST /catalog/v1/composers/unarchive 
curl -X POST "https://platform.revelator.com/catalog/v1/composers/unarchive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "composerIds": [6601, 6602]
}'
Example response 200 
{
"results": [
  {
    "id": 6601,
    "succeeded": true,
    "errors": null
  },
  {
    "id": 6602,
    "succeeded": true,
    "errors": null
  }
]
}