How to Check a Request Status

After you make a license request, you'll probably want to check the request status. Here, we demonstrate a few ways to do this using the available GET endpoints for license requests. We also explain how to interpret the status once you have it, and refer you to our list of all request statuses for descriptions, licensing progress, and more.

In this article:
Checking the status of an existing request All requests Single request by ID All requests on an album All requests for a track Single request for a track Interpreting a request status CanLicenseCurrently CanLicenseEver Description RoyaltyOwed RoyaltyRate Status

---

Checking the status of an existing request

You can check a request status using the available GET endpoints:

• GET /api/requests to get all requests
• GET /api/requests/{id} to get a single request by ID
• GET /api/albums/{id}/requests to get all requests on an album
• GET /api/tracks/{trackId}/requests to get all requests of a track
• GET /api/tracks/{trackId}/requests/{requestId} to get a single request by track ID and request ID

To use these endpoints (all but the first example), you will need the unique ID for each resource (request ID, album ID, and track 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 checking request statuses (and for updating and requesting additional units), we recommend saving them (track ID and request ID at a minimum) when creating a request.

Example 1 - All requests

To get all your requests, use the endpoint GET /api/requests. By default, this returns your 100 most recent requests sorted by date added descending. You can get additional requests using the available offset and limit URL parameters. Simply add them to the URL like this: GET /api/requests?offset=101&limit=100. We discuss in greater detail how to use offset and limit in our article on best practices, under the heading Smart Use of Resources.

Example 2 - Single request by ID

To get a single request by request ID, use the endpoint GET /api/requests/{id} where "{id}" is the request ID you want. The URL would look something like this: GET /api/requests/5525

Example 3 - All requests on an album

To get all requests on an album, use the endpoint GET /api/albums/{id}/requests where "{id}" is the album ID you want to get requests on. This will return all requests for that album sorted by date added descending. Paging is not supported, since the number or requests on an album will usually stay fairly low. The URL would look something like this: GET /api/albums/1234/requests

Example 4 - All requests for a track

To get all requests for a track, use the endpoint GET /api/tracks/{trackId}/requests where "{trackId}" is the ID of the track you want to get requests on. This will return all requests for that track sorted by date added descending. Paging is not supported, since the number or requests on a track will usually be low. The URL would look like this: GET /api/tracks/5432/requests

Example 5 - Single request for a track

To get a single request for a track, use the endpoint GET /api/tracks/{trackId}/requests/{requestId} where "{trackId}" is the ID of the track and "{requestId}" is the ID of the request you want. The URL would look like this: GET /api/tracks/5432/requests/4453

For all of the examples above, the response body would look something like this. Depending on the endpoint, many requests might be returned, or only one. For brevity, we show only one request in this example response:

                    
[
  {
    "dateAdded": "2018-09-20T15:21:41.893",
    "id": 321799,
    "status": {
      "canLicenseCurrently": true,
      "canLicenseEver": true,
      "description": "We are searching for the current copyright holders of this song.",
      "royaltyOwed": 10.5,
      "royaltyRate": 0.105,
      "status": "New"
    },
    "track": {
      "album": {
        "artist": "Mariah Carey",
        "dateAdded": "2018-09-20T15:21:41.893",
        "id": 92152,
        "title": "Heroes",
        "licensee": {
          "address": "123 Chestnut Street",
          "city": "Pittsburgh",
          "companyName": "US Steel",
          "country": "United States",
          "dateAdded": "2018-09-20T15:21:41.9",
          "email": "example@example.com",
          "externalLicenseeId": "ExampleUniqueID",
          "firstName": "Andrew",
          "id": "ebc0f4b9-a878-49e6-9eb4-13fd71908b5e",
          "lastName": "Carnegie",
          "phone1": "(123) 123-1234",
          "phone2": null,
          "phone3": null,
          "state": "PA",
          "zip": "15106"
        }
      },
      "dateAdded": "2018-09-20T15:21:41.893",
      "externalTrackId": null,
      "id": 228450,
      "isrcCode": null,
      "lengthInSeconds": 301,
      "releases": [
        {
          "dateAdded": "2018-09-20T15:21:41.893",
          "formatId": 1002,
          "formatTitle": "Digital Downloads",
          "id": 117367,
          "releaseMonth": 10,
          "releaseYear": 2018,
          "releaseQuantity": 100,
          "quantityLicensed": 0,
          "expectedOutletsOfDistribution": "CD Baby Pro"
        }
      ],
      "song": {
        "arrangedBy": null,
        "composedBy": null,
        "notes": null,
        "originalRecordingArtist": "Mariah Carey",
        "publishedBy": null,
        "title": "Hero"
      }
    }
  }
]
                        
                

Parsing the response and using it with your system is beyond the scope of this article. However, we do provide help and examples in our article on basic integration. For help interpreting the status details, read on.

---

Interpreting a request status

Let's examine the "status" portion of the response we get when we call the endpoints in the examples above:

            
    
    "status": {
      "canLicenseCurrently": true,
      "canLicenseEver": true,
      "description": "We are searching for the current copyright holders of this song.",
      "royaltyOwed": 10.5,
      "royaltyRate": 0.105,
      "status": "New"
    },
            
        

As you can see, five values are returned. Let's look at each one:

CanLicenseCurrently

This indicates whether it is currently appropriate for the licensee to make payment to clear the license request. Depending on how payments are structured in your partner agreement, you might not need this field. For some integrations, it will help identify whether now is the time to collect payment from your licensees. Note that payments for "New" requests might need to be refunded depending on what is discovered after the song is researched. If you wish to avoid refunds, you can wait until the request reaches the "Need Payment" status to collect payment from your users.

CanLicenseEver

This tells you whether you will ever be able to clear the request using our API cover song licensing service. There are several reasons why a request might not be possible or required. Mashups, parodies, songs with changes to lyrics or melodies, and songs not copyrighted in the United States usually cannot be cleared due to limitations of the law. Clearances for karaoke, background tracks, and other non-personal uses are also not allowed. Public domain and original songs do not require clearance. In all these cases, it is possible that the "CanLicenseEver" value will be false, meaning the request cannot or should not be cleared through our service.

Description

This is a short explanation of the request status in plain english. It can be used by your employees and displayed to customers as needed.

RoyaltyOwed

This is the total amount of royalties owed for this particular request in U.S. dollars. Note that this shows only what is owed for this one particular request. Other requests/releases (if any) for the track would have separate royalty charges. Depending on how payments are structured in your partner agreement with us, you can use this value to charge your licensees or to estimate your payments to us.

RoyaltyRate

The "RoyaltyRate" is the amount in U.S. dollars that is owed per unit distributed. Note that the rate will vary by format and track length. RoyaltyRate is multiplied by ReleaseQuantity to calculate RoyaltyOwed. Learn more about how the royalty rate is calculated.

Status

"Status" tells you what's going on with a particular request. Once you have a "Status" for a request, you can compare it against our list of all request statuses to gain some additional information. Feel free to replicate the table if that's helpful. If you do, make sure to keep the information current. If you wish to share information about the request status with your users, we suggest you use the descriptions we provide, although you are welcome to write your own as well. If you do that, just make sure to keep them current.

---

What's next?

If you haven't done so yet, you might want to read about using albums to organize requests and using wall posts to communicate with ESL.