Use this api to submit new or updates of your publishing data.
This API is designed for and dedicated to publishers for posting royalties associated to a musical production (track). If you are a label and you'd like to send us lyrics in bulk, please refer to our commercial department.
Such details include licensees and their respective ownership quotas, collected royalties on a per-territory basis, plus some additional metadata that helps us match your Work with other Works submitted by other sources that partecipate in the royalties collection, and with the songs in our catalog — e.g. ISRCs, Performers, alternate titles.
Please note that you are responsible for transmitting only trustworthy and verified data.
Request body, in JSON format, must conform to this structure:
{ "data": { "identifier": "CUSTOMERID100", // (REQUIRED) Your Work’s unique identifier . Submitting updated data with the same "identifier" creates a new version of the same Work. "title": "Vamos a la playa", // (REQUIRED) The Work’s title. "alternate_titles": [ // (RECOMMENDED) A list of known alternate titles. "work_title_1", "work_title_2" ], "iswc": "T0050012504", // (RECOMMENDED) The ISWC of the Work being submitted. "isrc": ["ITA610200283", "ITS040300291"], // (RECOMMENDED) A list of ISRCs that are known to be linked to the Work. "performers": [ // (RECOMMENDED) A list of known Performers. { "name": "Perormer name" } ], "owners": { // (RECOMMENDED) The right holders, split into Songwriters and Publishers. "publisher": [ { "identifier": "000002224", // (OPTIONAL) The Publisher’s unique identifier on your side. "name": "XW PUBLISHING (ITALY) S.R.L", // (REQUIRED) The Publisher’s name. "ipi": "00574052343", // (RECOMMENDED) The Publisher’s IPI. "role": "E", // (RECOMMENDED) The Publisher’s role (either "E", "SE" or "AM" for Original Publisher, Sub-Publisher or Administrator, respectively). "controlled": "Y", // (REQUIRED) The Publisher’s controlled status, either "Y" or "N". "mech_ownership_share": 5000, // (RECOMMENDED) The share of Mechanical rights owned by this Publisher. "perf_ownership_share": 5000, // (RECOMMENDED) The share of Performance rights owned by this Publisher. "sync_ownership_share": 10000 // (RECOMMENDED) The share of Micro-sync rights owned by this Publisher. } ], "writer": [ { "identifier": "000002225", // (OPTIONAL) The Writer’s unique identifier on your side. "name": "CARMELO LO GATTO", // (REQUIRED) The Writer’s name. "ipi": "00064163444", // (RECOMMENDED) The Writer’s IPI. "role": "C", // (RECOMMENDED) The Writer’s role (e.g. "CA" for Composer-Author, "C" for Composer, "A" for Author, …). "controlled": "Y", // (REQUIRED) The Writer’s controlled status, either "Y" or "N". "mech_ownership_share": 1600, // (RECOMMENDED) The share of Mechanical rights owned by this Writer. "perf_ownership_share": 1600, // (RECOMMENDED) The share of Performance rights owned by this Writer. "sync_ownership_share": 0 // (RECOMMENDED) The share of Micro-sync rights owned by this Writer. }, { "identifier": "300033927", "name": "STEFANO ANNIBALI", "ipi": "00122862771", "role": "CA", "controlled": "Y", "mech_ownership_share": 3400, "perf_ownership_share": 3400, "sync_ownership_share": 0 } ] }, "collection": { // Details on collected royalties, on a per-territory basis. "validity_begin": "2012-05-13", // (RECOMMENDED) Beginning of deal, in YYYY-MM-DD format. If omitted, the date of submission will be used instead. "validity_end": null, // (OPTIONAL) End of deal, in YYYY-MM-DD format, or NULL. "territories": [ // (REQUIRED) A list of territories where royalties are collected. { "code": "XW", // (REQUIRED) One of the territory codes configured for the Source. See below for further info. "mech_share": 10000, // (REQUIRED *) The share of Mechanical royalties collected in this territory. "perf_share": 10000, // (REQUIRED *) The share of Performance royalties collected in this territory. "sync_share": 10000 // (REQUIRED *) The share of Micro-sync royalties collected in this territory. // * At least one of `mech_share`, `perf_share`, `sync_share` must be provided, the others then become optional. } ] }, "lyrics": { // (OPTIONAL) Provide the lyrics for this Work along with its ownership details. "duration": 242, // (REQUIRED) The duration in seconds of the original recording. "lyrics": "Vamos a la playa\nA mí me gusta bailar\n...", // (REQUIRED) The lyrics for this Work, verses separated by line feed. Remember to encode strings properly as we're in JSON format. "lrc": "[00:12.345] Vamos a la playa\n..." // (OPTIONAL) Lyrics in LRC format. Make sure the last row has the time indication and an empty lyrics line. This time will correspond to the timing of the end of the last lyrics line, example: "[04:10.010] \n" } } }
An important note about shares: shares are represented as integers instead of decimals
for system portability. The value can be obtained from the percentage by multiplying by 100 and rounding.
For example, 100% becomes 10000, 50% becomes 5000, 12.50% becomes 1250,
33.3333% becomes 3333 and so on.
Remember that sum of ownership shares cannot be higher than 100%,
and that collected royalties for each territory must be lower than or equal to the sum of ownerships from
controlled licensees. These restrictions apply to all three types of rights independently.
When specifying territories for collections, the Territory code can be either:
IT, FR, US, CA, …
XW representing a worldwide collection (or WRD as an alias of XW).
work.territory.post API endpoint.
IT which includes countries IT, VA, SM (Italy, Vatican City, San Marino)
that custom Territory has precedence over the ISO 3166-1 code for country IT (Italy)!
Although this may seem confusing at first, it gives you the possibility to identify a country with
the union of the country itself and its enclaves, its overseas protectorates, or whatever else.
This method requires authenticating with an API key that is associated with a verified publisher account. If you want to submit your works you have to register as a publisher in Musixmatch.
{ "data": { "identifier": "00000000196005", "title": "Yellow Submarine", "owners": { "publisher": [ { "name": "Sony/Atv Tunes Llc", "controlled": "Y" } ], "writer": [ { "name": "John Lennon", "role": "CA", "controlled": "Y", "mech_ownership_share": 5000, "sync_ownership_share": 5000 }, { "name": "Paul McCartney", "role": "CA", "controlled": "Y", "mech_ownership_share": 5000, "sync_ownership_share": 5000 } ] }, "collection": { "validity_begin": "2012-01-01", "territories": [ { "name": "WRD", "mech_share": 10000, "sync_share": 10000 } ] } } }
{ "message": { "header": { "status_code": 200, "execute_time": 0.10906291007996 }, "body": { "identifier": "00000000196005", "title": "Yellow Submarine", // ... } } }