Loading


How to Use Wall Posts to Communicate with Easy Song Licensing

One powerful feature of the Easy Song Licensing API is the ability to make wall posts to communicate with our licensing experts. Every album has its own wall, where your employees, our employees, and licensees can communicate about the album (similar to a Facebook timeline). Every new wall post is emailed to our team and recorded on the album wall. Posts can be public (visible to the licensee), or private (visible only to employees). Use wall posts to send additional information, ask questions, and receive clarification about request statuses.

Note - This article covers the HTTP and JSON used to create and manage wall posts using HTTP POST, GET, and DELETE requests. For detailed help constructing an HTTP GET request, check out our article on basic integration.
In this article:
Wall post endpoints Get all wall posts Create a new wall post Delete a wall post Conclusion

Wall post endpoints

You can create and manage wall posts using the following endpoints:

  • GET /api/tracks/{trackId}/wallposts to get all wall posts on the album of the specified track
  • POST /api/tracks/{trackId}/wallposts to create a new wall post on the album of the specified track
  • DELETE /api/tracks/{trackId}/wallposts/{wallPostId} to delete a wall post you added

To use these endpoints, you need to provide the unique track ID that is returned in the response when you create an initial license request. To DELETE, you will also need the unique wall post ID that is returned when you create a wall post. Because the track ID is required to manage wall posts, we recommend saving it each time you create a request. You may also want to save wall post IDs for easier access should you wish to delete posts. Below, we explore each wall post endpoint in detail.

Good to know - It's currently not possible to edit a wall post. If you need to make a change, DELETE and POST again.

Example 1 - Get all wall posts on the album of a specified track

To get all wall posts for an album, use the endpoint GET /api/tracks/{trackId}/wallposts. Provide the track ID of any track on the album you wish to get wall posts for. For example, supposing we wanted wall posts for track ID 431, the URL would look like this: GET /api/tracks/431/wallposts. By default, this returns the 100 most recent wall posts, public and private, sorted by date added descending. You can get additional wall posts using the available offset and limit URL parameters. Simply add them to the URL like this: GET /api/tracks/431/wallposts?offset=101&limit=100. We discuss in greater detail how to use offset and limit in our article on best practices, under the heading Use resources efficiently. You can also change the sort direction by appending sort=asc to the URL. You can filter public and private by appending isprivate=false and isprivate=true respectively. For example, if you wanted the first 50 public wall posts sorted by date ascending, you would construct the following URL: GET /api/tracks/431/wallposts?limit=50&sort=asc&isprivate=false

Example 2 - Create a new wall post on the album of a specified track

To create a new wall post, use the endpoint POST /api/tracks/{trackId}/wallposts, where "{trackId} is the ID of the track whose album you wish to link this wall post to. In your JSON, provide the required "message" field and the optional "isprivate" if you wish. For example:

To add a wall post to track 431 with the default private status:
POST /api/tracks/431/wallposts 
    
{
  "message": "We are in a hurry on this one. Is there any way you can expedite licensing on this?"
}
or...
POST /api/tracks/431/wallposts 
    
{
  "message": "Hi ESL! Can you please explain why this song is unavailable for licensing?"
}

To add a public wall post to track 431, visible to the licensee:
POST /api/tracks/431/wallposts 
    
{
  "isPrivate": false,
  "message": "Hi Charles! We need to know the length of your recording of this song in minutes and seconds before we can proceed with licensing. Please post to your album wall when you know it."
}

Good to know - The licensee typically won't see wall posts unless you expose them through a graphical user interface you build. They will see public wall posts if they view their API-created projects through their EasySongLicensing.com account.
Emails - Currently, the API does not send emails to licensees, even for public wall posts. If you want this feature, it's something you can certainly build into your integration. Emails are sent to our team every time a wall post is added (public or private).
Best practice - Use wall posts liberally. They are super helpful for providing quality customer service and when coming back to a request months later. When adding wall posts, use isprivate=false if the licensee could benefit from seeing the post. Even if they currently have no way of seeing the post, the proper designation will help by exposing 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.

Delete a wall post permanently

You can permanently delete a single wall post using the endpoint DELETE /api/tracks/{trackId}/wallposts/{wallPostId}. In the URL, provide the "{trackId}" the post is associated with and the "{wallPostId}" you want to delete. The URL would look something like this: DELETE /api/tracks/431/wallposts/23412

Warning - Deleting a wall post is permanent and cannot be undone.

Conclusion

You can create and manage wall posts using three available endpoints: GET /api/tracks/{trackId}/wallposts, POST /api/tracks/{trackId}/wallposts, and DELETE /api/tracks/{trackId}/wallposts/{wallPostId}. We encourage you to use wall posts liberally, since they make a big difference with customer service and record keeping. Each time you create a wall post, an email is sent to our licensing team, making it a great way to stay in touch and get support for your requests. When you create a wall post, it's best to use the proper designation of isprivate=false if the post should be publicly visible to the licensee. Although they can't see any wall posts unless you build an interface for them, the proper privacy designation will give you the option to build an interface in the future. Also, your licensees can view requests and wall posts through their EasySongLicensing.com accounts if they have one.

What next?

If you've been going in order, you've read all the main articles about how to use the API. We also have several articles to supplement the reference. It's possible you've read some of these already. They list the fields and data types, release formats, request statuses, error messages, and terms you will encounter, and document changes to the API.

Next Article - Fields and Data Types
https://developer.easysonglicensing.com/documentation/008-using-wall-posts-with-the-easy-song-licensing-api.aspx