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": "WRD",       // (REQUIRED) One of the territory codes configured for the Source.
          "mech_share": 10000, // (RECOMMENDED) The share of Mechanical royalties collected in this territory.
          "perf_share": 10000, // (RECOMMENDED) The share of Performance royalties collected in this territory.
          "sync_share": 10000  // (RECOMMENDED) The share of Micro-sync royalties collected in this territory.
        }
      ]
    }
  }
}
            

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.

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",
      // ...
    }
  }
}