How to Post a License Request (Clear a Cover Song)

The Easy Song Licensing API is primarily used to make requests for us to clear cover songs. Here, we show you how to make the initial request and how to license additional units. We also show off some options and warn of potential problems.

Note - This article covers the HTTP and JSON used to post new license requests using HTTP POST requests. For detailed help constructing an HTTP POST request, check out our article on basic integration.

In this article:
Before you begin Adding a new request (initial request) Licensing additional units Release date limitations How to handle medleys

Before you begin

Before you post your first request, you might want to review the fields and data types and available release formats. You should also decide how you will organize your requests using albums. Finally, check out the following warnings and notes for a smooth experience:

Careful - Avoid creating duplicate licensees. Save the unique licensee ID that is returned in the response. Use it on subsequent requests for that licensee and they will all point to the one licensee object in the database. This way, you can update licensee info in one place and affect all requests for that particular licensee.

Important - Save the unique track ID from the response and use it to access the request later. This is required to license additional units. You can also save the unique album ID and release ID.

Medleys - To clear a medley, create an initial request for the medley as a whole AND for each song part that makes up the medley. Licensing will be required for each "song part". Learn more.

Release date limitations - For legal reasons, the release month cannot be the current month when the current date is the 20th of the month or later and the release date cannot be in the past. Learn more.

Changes limitations - After you post a request, there are some limitations on changes that are allowed. Song info cannot be changed after the request has been linked to a song in our database. Album, track, and release info cannot be changed after licensing has begun. Learn more in the article on updating a request.

Unknown album title and artist - For the album title, if the album has no title, you can put "Untitled". If this is a single, you can use the song title or "Single". For the album artist, if the album has more than one artist, such as a compilation, you can list all artists, or put "Various". If the album artist is not known, you can use the licensee's full name.

Expected outlets of distribution - If the Interactive Audio Streams format is requested, we will need to know where the streams will be released. When posting, provide a brief summary of the distribution outlets. Popular choices include CD Baby, ReverbNation, personal websites, and band pages. If using a distribution package, this can be summarized by naming the package. For example "All CD Baby Stores", "CD Baby Pro", and "CD Baby Standard" are all acceptable values. If you are not sure, check with the digital distributor (CD Baby, TuneCore, Symphonic) or the client.

Best practice - Create initial requests only if the track has not been licensed with us before (no previous request exists). Check for existing requests using saved track/request IDs. If a previous request was made, use the POST /api/tracks/{trackId}/requests endpoint to license additional units instead.

Adding a new request (initial request)

If this is a new request, meaning you did not previously request clearance of this song for this particular licensee/album/track, you can create a new request using the POST /api/requests endpoint. Provide the required fields, including licensee, album, release, track, and song info.

                    
{
  "track": {
    "album": {
      "artist": "Mariah Carey",
      "title": "Heroes",
      "licensee": {
        "address": "123 Chestnut Street",
        "city": "Pittsburgh",
        "companyName": "US Steel",
        "country": "United States",
        "email": "example@example.com",
        "externalLicenseeId": "ExampleUniqueID",
        "firstName": "Andrew",
        "lastName": "Carnegie",
        "phone1": "(123) 123-1234",
        "state": "PA",
        "zip": "15106"
      }
    },
    "lengthInSeconds": 301,
    "releases": [
      {
        "formatId": 1002,
        "releaseMonth": 10,
        "releaseYear": 2018,
        "releaseQuantity": 25,
        "expectedOutletsOfDistribution": "CD Baby Pro"
      }
    ],
    "song": {
      "originalRecordingArtist": "Mariah Carey",
      "title": "Hero"
    }
  }
}

Note that in the example above, we post complete information for a new licensee. It's best to do this only once for each licensee. The first time you do it, you can get the unique licensee ID from the response and save it for future use. Then, when making subsequent requests for this licensee, provide the unique licensee ID instead of complete licensee info. It would look like this:

                    
{
  "track": {
    "album":{
      artist": "Mariah Carey",
      "title": "Heroes",
	    "licensee": {
		"id": "badf45ab-041f-435b-be4b-8bf2b511c539"
	    }
    },
    "externalTrackId": "124",
    "lengthInSeconds": 214,
    "releases": [
      {
        "id": 8
        "formatId": 1,
        "releaseMonth": 10,
        "releaseYear": 2018,
        "releaseQuantity": 0,
        "expectedOutletsOfDistribution": "CD Baby Pro"
      }
    ],
    "song": {
      "originalRecordingArtist": "Janet Jackson",
      "title": "Again"
    },
  }
}

Notice we skip sending all that licensee info the second time. Instead we use the licensee's unique ID. This prevents the creation of duplicate licensees while appropriately pointing all requests to the one unique licensee.

The above two code examples demonstrate how you should POST every initial cover song license request (non-reorder). Check out the next section to learn how to request additional units (reorder) after the initial request has been made.

Licensing additional units

After the initial license request has been made, a common task is clearing additional units. To do this, create a new (additional) request using the endpoint POST /api/tracks/{trackId}/requests. In the endpoint URL, provide the track ID you want additional units for. This will create a new release and request and link them to the existing licensee, album and track.

Warning - By default, the POST /api/tracks/{trackId}/requests endpoint creates a new request for every track on the album. This is not a problem if you use the default "one track per album" method of organizing by album. However, if you add multiple tracks to an album, you need to use this endpoint carefully. Check out our article on using albums for more information.

Medleys - To license additional units for a medley, remember to create an additional request for the medley as a whole AND for each song part that makes up the medley. Licensing will be required for each "song part". Learn more.

POST /api/tracks/1/requests

                    
{
  "releaseQuantity": 100,
  "releaseMonth": 10,
  "releaseYear": 2018,
  "formatId": 1002
}

The example above will add a new request to release 100 digital downloads of track ID 1. Note that format ID 1002 is for digital downloads (view all release formats). The new release/request will link to the specified track and share the track, album, and licensee that were created when the initial request was made. This is the right way to do a reorder because it keeps all releases/requests together with the original track and album, allowing easy calculation of total units requested and units licensed going forward.

Release date limitations

For legal reasons, there are some limitations related to what you can provide for the release date:

Future releases only - The release date must always be in the future. If you need to clear a past release, check out our Custom Licensing services or contact us.
Monthly deadline is the 20th - The release month cannot be the current month when the current date is the 20th of the month or later. This allows time for processing and for the copyright holder to receive the request. It prevents them mistakenly thinking the release date happened prior to their receipt of the request.

If you try to provide release info outside the scope of these limitations, you will get an error. If you have concerns with a particular request, let us know with a wall post or contact us.

How to handle medleys

When clearing medleys, it's important to create a request for the medley as a whole AND for each song part that makes up the medley. Remember to do this when you create the initial request and when you create additional requests (reorder). Note that licensing will be required and royalties will be due for all requests that represent a "song part" (Yes, that's 3X the royalties. We hear complaints about this all the time, but that's the law). Although no royalties will be required for the request that represents the "medley as a whole", we prefer to have this information for good record keeping. When providing the track length, submit the length of the segment being requested. For the entire medley, that would be the length of the entire track. For each song part, it would be the length of that song part. For example:

Request 1 (Medley as a whole) - Highlights from Disney's "The Little Mermaid", Arranged by Michael Sweeney (5:23)

Request 2 (Song part 1 of 3) - "Under the Sea", Composed by Alan Menken and Howard Ashman (2:15)
Request 3 (Song part 2 of 3) - "Kiss the Girl", Composed by Alan Menken and Howard Ashman (1:25)
Request 4 (Song part 3 of 3) - "Part of Your World", Composed by Alan Menken and Howard Ashman (1:43)

Learn how to update a request or check a request status.

Next Article - Update a Request

Loading