How to Update a License Request

After you create a license request, you might need to make a change. This article shows you how to update an existing request. There are some limitations. Once the request has been linked to a song in our database, song changes are not allowed. Once licensing has begun, changes are limited. Read on to learn more.

In this article:
Updating an existing request Updating album info Updating licensee info Updating track and song info Updating release info Limitations on when updating is allowed

---

Updating an existing request

You can update the various components of an existing request using the available PATCH endpoints:

• PATCH /api/albums/{id} to update album info
• PATCH /api/licensees/{id} to update the licensee
• PATCH /api/tracks/{id} to update track and song info
• PATCH /api/tracks/{id}/releases/{releaseId} to update release info

To use these endpoints, you will need the unique ID for each resource (album ID, licensee ID, track ID, and release ID respectively). These IDs are returned in the response when you create an initial request. You can also get them from GET /api/requests/{id} if you know the request ID. Because these IDs are required for updates (and for requesting additional units), we recommend saving them (track ID and request ID at a minimum) when creating a request.

Example 1 - Updating album info

To update album info, we'll use the endpoint patch /api/albums/{id}. In the URL, we will insert the unique album ID of the album we want to update. Our body will include the JSON to update a particular field. The JSON includes a new "value", the "path" of the object field whose value we want to change (for example, album "title" or "artist"), and "op", the standard JSON PATCH operation to perform. You'll probably use "replace" in most cases. Click here to learn more about JSON patch .

Change the album title to "Heroez"
patch /api/albums/1

                    
[
  {
    "value": "Heroez",
    "path": "title",
    "op": "replace"
  }
]
                    
                

Change the album artist to "Janet Jackson"
patch /api/albums/1

                    
[
  {
    "value": "Janet Jackson",
    "path": "artist",
    "op": "replace"
  }
]
                    
                

Example 2 - Updating licensee info

Licensee info is updated using the endpoint patch /api/licensees/{id}. In the URL, insert the unique ID of the licensee you want to update. Like in example 1, the body should include the JSON to update the value of a particular path/field, in this case, the licensee's "companyName".

Change the company name to "The Electric Company"
patch /api/licensees/a298460c-ed4c-41b0-b700-8d46187b2f52

                    
[
  {
    "value": "The Electric Company",
    "path": "companyName",
    "op": "replace"
  }
]
                    
                

Example 3 - Updating track and song info

Track info can be updated using the endpoint patch /api/tracks/{id}. Song info can be updated here as well, using the path "song/FIELD". For example the path "song/title" can be used to update the song title. In the URL, insert the unique ID of the track you want to update. The body should include the JSON to update the value at a particular path/field.

Change the track length in seconds:
patch /api/tracks/1

                    
[
  {
    "value": 202,
    "path": "lengthInSeconds",
    "op": "replace"
  }
]
                    
                

Notice we provide a "value" of type integer, since that's the proper type for this path as specified in the reference. 202 seconds is the same as three minutes, twenty-two seconds (3:22).

Change the song title:
patch /api/tracks/1

                    
[
  {
    "value": "Auld Lang Syne",
    "path": "song/title",
    "op": "replace"
  }
]
                    
                

Add notes about the song to assist with research:
patch /api/tracks/1

                    
[
  {
    "value": "We think this might be in the public domain. We found this link: https://en.wikipedia.org/wiki/File:Auld_Lang_Syne.ogg",
    "path": "song/notes",
    "op": "replace"
  }
]
                    
                

Example 4 - Updating release info

To update release info, use the endpoint patch /api/tracks/{id}/releases/{releaseId}. You will need the unique track and release IDs to the release you want to update. If necessary, you can get this from get /api/requests/{id}. In the URL, insert the unique track and release IDs. The body should include the JSON to update the value at a particular path/field. Let's make some changes!

Change the format to compact discs:
patch /api/tracks/1/releases/17

                    
[
  {
    "value": 1001,
    "path": "formatId",
    "op": "replace"
  }
]
                    
                

Change the quantity to 27:
patch /api/tracks/1/releases/17

                    
[
  {
    "value": 27,
    "path": "releaseQuantity",
    "op": "replace"
  }
]
                    
                

Change the release month to December:
patch /api/tracks/1/releases/17

                    
[
  {
    "value": 12,
    "path": "releaseMonth",
    "op": "replace"
  }
]
                    
                

---

Limitations on when updating is allowed

To preserve the integrity and legality of the request, there are some limitations on when updates are allowed. Once a song has been linked in our database, song changes are not allowed. Once licensing has begun, changes are limited. Below, we break down what can be updated when:

• Album - the album title and album artist can be updated until licensing has begun.
• Licensee - all of the licensee's personal info (name, phone, email, etc.) can be updated at any time.
• Track - track length can be changed up until licensing has begun. One exception: if the track length is missing (it is 0:00 or null) it can be provided anytime, even after licensing has begun.
• Song - song title, artist, composer, arranger etc. can be updated until the request has been linked to a song in our database.
• Release - release month, year, quantity, format, etc. can be updated until licensing has begun.

If you try to update any of this info outside the scope of these limitations, you will get an error. If you must make the change, let us know with a wall post or contact us.

---

Next up

Learn how to check a request status and interpret what it means.