WORK.POST

Submit a work’s details.

Use this api to submit new or updates of your publishing data.

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.


Parameters

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": [           // (OPTIONAL) A list of known alternate titles.
      { "title": "work title goes here" }
    ],
    "iswc": "T0050012504",                    // (OPTIONAL) 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": { // (REQUIRED) 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": {                   // (REQUIRED) 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:

  1. A two-letter country code ( ISO 3166-1 alpha-2 code ). For example: IT, FR, US, CA, …
  2. XW representing a worldwide collection (or WRD as an alias of XW).
  3. A territory code previously created using the work.territory.post API endpoint.
    Please note that if you created a custom Territory whose name conflicts with one of the codes described above, the custom Territory takes precedence — e.g. if you created a custom Territory for the Italian peninsula named 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.

Authentication

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.


Examples

Submit a new work or update an existing one
Request
Submit data for Work “Yellow Submarine”
work.post
JSON request payload
{
  "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
        }
      ]
    }
  }
}
Json Response
{
  "message": {
    "header": {
      "status_code": 200,
      "execute_time": 0.10906291007996
    },
    "body": {
      "identifier": "00000000196005",
      "title": "Yellow Submarine",
      // ...
    }
  }
}