Building Fundraising Leaderboards with the Classy API

Last Updated: Jul 11, 2018 08:48AM PDT

This article assumes you have read through our Getting Started Guide and have your API key and secret ready, with an access token granted.

Helpful links:

Organization & Campaign Level Leaderboards

The Classy API V2 is RESTful. This means, among other things, that the code to fetch the same endpoint (say, fundraising pages) from various resources (say, organization and campaign levels) is consistent.

Organizational Level

API call: GET{org_id}/fundraising-pages

Campaign Level

API call: GET{campaign_id}/fundraising-pages

Note: From now on, “GET” will be omitted for the purpose of this instruction. “Https://” is the base URL for all Classy API calls and it is assumed you will always prepend this to your URL using a GET method.

Adding Parameters to Your API Call

Take a look at the JSON response from both calls. If you’d only like to fetch information like the fundraising page ID, campaign ID and member ID, then you’re done! But, chances are you’d like the data from the tables associated with that fundraising page, i.e. fundraiser’s photo, first and last name, campaign title, etc.

The “With” Parameter

Developer at {{nonprofit_name}}, meet the nifty (and optional) “?with” parameter. This is like joining two database tables to save you an API call. Rather than iterating through a collection of all fundraising pages for your organization, and then making an additional call for every fundraising page using the member_id supplied in the JSON response to retrieve member information (first and last name, photo, etc.), you can make this all in one call.

API call: /organizations/{org_id}/fundraising-pages?with=member

This puts that member information right there into the original response for you and saves you processing time by decreasing calls to the Classy API. Keep an eye out for which resources you may join using “with” parameters on each endpoint as you read through the Classy API documentation.

The “Aggregates=true” Parameter

Appending aggregates=true to the end of your URL is a quick trick to get even more information, including the financial information from each fundraising page. You’ll find total_raised, total_donors, total_donations, goal, etc.

The "Sort" Parameter

Our Github article on making a campaign leaderboard request sorts by total raised of each fundraising page in descending order (“sort=total_raised:desc”). Similarly, you could sort the JSON response by other attributes such as percent_to_goal, total_donations, total_donors, average_donation, etc. Some folks have added extra logic for “Needs help” and “Almost to Goal” categories to give inspiration to donors who come to their website unsure of who to contribute to. Time to get creative!

Summing It All Up

Final API call: /organizations/{your_org_id}/fundraising-pages?aggregates=true&sort=total_raised:desc&with=member

At this point, you have all the necessary parameters to create your leaderboard. This API call will provide member first and last name, goal, and total raised.