Easy Song Licensing API Best Practices

As with any API, it's important that your integration be fault-tolerant and smart with its use of resources. By following a few simple suggestions, you can organize your requests appropriately and prevent duplicate licensees, albums, and tracks. You can enhance your customer service experience and stay in communication with our team by using our powerful wall posts feature. Finally, you can make a difference for your users, the copyright holders, and us, by screening licensing uses.

Handle and log errors

Keep in mind that errors will sometimes happen. For example, you might experience a connection problem between your servers and Easy Song Licensing's, or a rare outage. To make sure that your integration is as reliable as it can be, you should always handle errors. If an API call returns an error, please log the call in as much detail as you can, including what you sent; the entire error response; and headers. That way, if you need to contact us, we will be better able to help.

Use resources efficiently

Some endpoints return large sets of data. You can improve the efficiency of your calls by using the offset and limit parameters (when available) to select only what you need. Note that by default, any endpoints with these parameters return only the first 100 objects. When you need more, you can use the offset and limit parameters. When you do, please smartly combine offset with limit to keep the response a reasonable size. For example, just setting offset to 0 and limit to 5000 would probably not be the best solution. Instead, bite off chunks of around 100 objects as needed. For example,

Note the sort order

The default sort order for all responses is date created descending. In other words, the newest objects are returned first, followed by older objects further down the list. Currently, only wall posts allow changing that sort order.

Understand data set limits

As mentioned above, endpoints with large sets of data return only 100 objects by default. You can request more using the available offset and limit parameters. Other endpoints naturally return smaller sets of data. For example, tracks on an album is usually under 100. These endpoints return all data with no limits. They do not require or offer the limiting parameters used by the endpoints with larger data set responses.

Limit the number of calls

As a rule, it's best to make fewer calls when possible. Balance your calls with your list size. As an extreme example, making hundreds of calls for a single licensee to build a list of licensees would not be good. A better solution would be to make one call selecting a list of licensees, then parsing that response to build your list.

Choose your method for using albums

Before you make any requests, you should choose one method for using albums. Commit to that method and stick to it. This will give your users a consistent experience and simplify troubleshooting should any issues arise.

Keep licensees unique

When you post an initial request (POST /api/requests), licensee info is required. If you provide the same info each time, you will create dozens of rows in the database of licensees with the same contact info, and that's not good. The right way to do this is to save the unique licensee ID from your first request, and use it again for all subsequent requests for that licensee.

Do reorders right

When you post an initial request using POST /api/requests, a new album, track, and release are created. If you repeat this action for a reorder, a separate album, track, and release are created, and they don't link to the original. Instead, you now have two tracks in the database, with nothing to indicate that they are related (other than perhaps a shared album title string). That's a problem because you can't easily associate all requests and releases of what should be one track. For example, you can't get the total quantity licensed of the track.

When additional units are required, the right way to make your request is with the POST /api/tracks/{trackId}/requests endpoint. This builds upon the existing album and track, and keeps the all of the releases and requests associated.

Use wall posts liberally

Wall posts are a way for you to communicate with us. They are super helpful for providing good customer service, and we recommend you use them liberally. When adding wall posts, use isprivate=false if the licensee could benefit from seeing the post. Even if they have no way of seeing the post right now, the proper designation will expose the post if an interface is added in the future, or if the licensee views their request in their EasySongLicensing.com account. If the post is only for you and ESL, you can leave off isprivate and the post will be private by default (visible only to your employees and ESL).

Screen client uses for proper licensing

Easy Song Licensing prides itself on the thorough and accurate handling of each license request. This is good for the client, the copyright holders, and the music industry. You can make a difference in the following ways:

• Explain the limitations of the compulsory mechanical licensing law. Consider adding checkboxes to confirm.
• Identify all uses and release formats. For example, "Releasing on YouTube?". Consider adding checkboxes for each format.
• Refer clients to us for Custom Licensing or direct them how to clear other uses when necessary. Currently only compulsory mechanical licenses (cover song licenses in compliance with the compulsory law) are available through the API. Currently, no video uses are available through the API.
• Pay attention to quantities. Provide actual distribution numbers when possible. Physical product should be licensed upfront for each copy released (including promos and free units).
• Provide accurate release dates. Past release dates cannot legally be cleared under compulsory law and are not accepted by the API. Never knowingly submit a current release date if the release was actually in the past. If necessary, past releases can be cleared via Custom Licensing.
• Never knowingly provide misinformation. Incorporate our Terms of Use as explained in our Getting Started tutorial. Require acceptance of the Terms of Use before clearing licenses for a user.
• Watch for red flags. If you see potential problems, stop licensing and ask the user. For example, an album title of "Mashups for Your Karaoke Business!" tells you this release probably breaks a couple of compulsory law rules.

Although some of this might seem burdensome, it's important to protect you, your clients, and us. It's also good for the music business and the right thing to do.

Next up?

Thanks for reading all that! Guess you're ready to post a request.