donordrive / publicapi

Documentation and Examples for the DonorDrive Public API

DonorDrive Public API

The DonorDrive Public API makes it easy to build integrations using public event, participant, and team data through a RESTful interface. Data is retrieved via GET requests and successful responses are returned in JSON format. The API is completely open to integrations using the interface in a responsible manner.

Please limit requests to one every 15 seconds. Make use of the etag and if-none-match headers to reduce network overhead on redundant API calls. Please don't abuse the API, or we may be forced to rate-limit requests. A reasonable example of the interval is as follows: when updating a streaming overlay, polling the participant endpoint every 15 seconds and checking for a change in etag (HTTP 200). If a change is detected, use the participantID to get additional information from nested endpoints, and display the combined information on the streaming overlay.

For general inquiries and requests for larger volume integrations, please email [email protected] for assistance.

Table of Contents

• Overview
• How-Tos
• Demos
• Resources
  • About
  • Activity
  • Badges
  • Donations
  • Donors
  • Events
  • Incentives
  • Milestones
  • Participants
  • Teams
  • Team Groups

publicapi's Issues

Ability to view past Incentives

It would be nice to have the ability to view Incentives that have passed their End Date. Gives the ability to track statistically which incentives are working and which incentives are not working. Also, from a list perspective, when viewing past donations you can associate that donation to incentive. Sometimes a few of us don't get around to redeeming incentives til past their end date.

Currently, /incentives only shows active incentives right now.

isComplete not returned on Milestones request

To Reproduce:
Visit my request : https://www.extra-life.org/api/participants/400560/milestones

The request is not pulling isComplete when called.

Also, is it possible to make it filterable on request as well?

User getting 429 error

User of my software https://github.com/djotaku/ELDonationTracker is getting 429. I'm able to change my user ID to be her without issue. I used my software today so I know I'm not hitting the API too hard. Ideas on why she can't access the API?

Thanks

API endpoints for superteams?

I'm looking for, and can't seem to find, any API endpoints for superteam data. For reference a superteam is a team that can have both participants and other teams contributing towards a total goal (example here).

What I'm looking to do is grab the donation total and goal numbers from the superteam without having to aggregate all of the subteams and add up the total "manually."

Team API endpoint for number of team members

It's possible I'm missing something, but when I look at https://www.extra-life.org/api/teams/44013 I don't see a way of knowing how many team members are on the team. If I go to https://extra-life.org/api/teams/44013/participants I could check if there are 100 and that would tell me that MAYBE there are 101, but it'd be easier if I could know ahead of time.

Thanks!

Feature Request: Simple endpoint values to sort results

We currently require users to have an understanding of SQL knowledge to filter and sort the results of various endpoints. It maybe be beneficial to have /top, /newest (alias for our current default), /oldest as additional values in the endpoint path, that would allow users to grab relevant information without having to get into the muck of SQL:

/api/participants/newest - would retrieve the newest participants
/api/participants/1234/donations/top - would retrieve single-donations in descending order of amount
/api/events/500/teams/top - would retrieve the top fundraising teams for a given event (id: 500)

Expose #of years fundraising

On the website we can see how many years someone has been an ExtraLifer, it would be amazing if we could have access to that information through the API so we can display that in discord alerts when showing participant data.

API Endpoints Inaccessible via App

Many complaints on Discord, so it's not just my App. Endpoints accessible via website.

I'm getting a 403: Forbidden Error

Possible to expose supporting hospital data?

Something I should have submitted earlier. In participants, it would be very useful to be able to grab the supporting hospital from the API to more easily grab the data with our script (we have a variety of people supporting different hospitals on our stream).

No donationID for anonymous donors in donations response

Not sure what changed but there's now no donationID in the JSON response of donations for anonymous donors. This is supposed to be a guaranteed field.

Example here with the third entry. https://extralife.donordrive.com/api/participants/448764/donations

Expose Fulfillment Note on Incentives

It'd be nice to be able to display the Fulfillment Notes when a donor donates for a certain Incentive.

Currently it's buried in Donor Report.

Use Case:
While streaming, it'd be nice to have an alert that says exactly what the fulfillment note for the incentive that was redeemed.

CORS Policy Error

Hey folks, I haven't used the API since last November. But I was just updating my site with the new Extra-Life donor IDs and I noticed my calls are failing with:

Access to XMLHttpRequest at 'https://www.extra-life.org/api/participants/480323?_=1655251911412' from origin 'https://stj.watch' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Is this expected? Is there something I need to change to get CORS to work?

Include `sumPledges` in teams endpoints

sumPledges is offered as a field inside the /participants endpoints. It would be nice for this field to be accessible from /teams endpoints as well.

Getting all of the donations from an endpoint?

Is there a way to get all the donations from the donor drive API endpoint? The array return from a GET request seems to be limited to 100 with setting the limit URL parameter.

Thanks,
Greg

Completed Boolean on Milestone API Endpoint

Looking at the Milestone metadata it would be nice to be able to have something (possibly a bool) that the milestone was reached. Comparing the milestone fundraising goal to the total raised by the participant.

This would make it easier to work with rather than pulling participants information as well as milestone information.

Milestone.Completed = Milestone.FundraisingGoal <= Participants.SumDonations

Thank you

Feature Request: Get Participant Stream

Would it be possible to return the stream of a given participant? I am now able to add my stream to my donation page, and it would be great to get a list of all of the streams that my team members are using. I am working on a site to showcase all of the team, somewhat simultaneously, and this would be a great feature.

Incomprehensible currency conversion

I am trying to convert dollars into rubles, approximately using this code:

`extracted_currency = 'USD';
price_extraction = 30.58;

						currencyConverter.from( extracted_currency ).to( "RUB" ).amount( price_extraction ).convert().then((response) => {


							console.log( response );
						})`

But the answer comes with a rather strange result:
`E:\multi>node index.js
2

The library is able to work with fractional numbers and if so, how do I configure it?

I read the documentation, but I didn't find anything like that...

Pegging to a specific API version doesn't allow sorting to work

See
https://www.extra-life.org/api/teams/55779/participants?orderBy=sumDonations%20DESC?version=1.2
vs
https://www.extra-life.org/api/teams/55779/participants?orderBy=sumDonations%20DESC

The second one is properly ordered. The first is not.

Retrieve hospital based leaderboard data

It would be really cool to be able to retrieve the hospital based leaderboard data to make a dashboard similar to the JavaScript demo in the Public API repo.

Custom Fields in API

Are custom fields exposed in the public API? I need access to them in order to filter a response correctly.

User Flow Implementation for Participant IDs

Are there any plans for this years DonorDrive campaigns to be able to obtain a Participants ID using some kind of authorization flow?

I'd really like to be able to implement a nice UI/UX flow rather than just asking somebody to input their Participant ID into an input field.

None of the Public API uses any kind of OAuth authorization so an OAuth flow wouldn't be needed, but something similar to it would be much appreciated.

• Redirect a user from my site to DonorDrive/ExtraLife
• Show a Confirm/Deny to sharing the ID with my site
• Redirect back to my site with some kind of token so I can use that to get the Participant ID

Thanks

Retrieve the donations sum, and target, shown on event page

I am looking at an event: https://lanfest.donordrive.com/index.cfm?fuseaction=donorDrive.event&eventID=510

The event page displays a target and a current value:

The public API for the event only returns the following:

{
    "endDateUTC": "2020-04-14T02:00:00.0+0000",
    "eventID": 510,
    "timezone": "America/New_York",
    "type": "P",
    "startDateUTC": "2020-04-10T22:00:00.0+0000",
    "name": "Corona Clash"
}

I did not see a means in API documentation to retrieve either the target ($5000 in the image) or the current ($90 in the image) so I am filing this issue to request that functionality. This event does not have any teams.

Consistancy on API Endpoints

Dealing with a weird bug right now due to the fact that anonymous donors don't appear on the donors endpoint while they do appear on the donations endpoint. Could we have anonymous donors appear on the donors endpiont and just not have a name attribute as you do with donations?

Offer a single request participant/team list

Would save a lot of time and access calls if you could offer a way to get the entire list of participants/teams in a single request. I'd expect it to be a very limited response set per entry.

I'd expect something like this for participant entries:

{
    "displayName": "Liam Bonham",
    "participantID": 19265,
    "teamName": "The Bonhams",
    "teamID": 8775
 }

I'd expect something like this for team entries:

{
    "name": "The Bonhams",
    "teamID": 8775
}

The purpose of such lists would be to facilitate downloading a list that can be used to search for a participant or team by name.

(edit) Now that I've taken a closer look at the data, there is no point in adding event information as it's the same for every participant/team.

Request Multiple Participants

I'm building a Twitch app that can write to the chat when donations to a participant or team show up. The frequency I was thinking of is checking every minute (since folks are watching live).

While I'm designing this implementation, I'm nervous about making too many calls to the DonorDrive API. If I'm keeping it simple, I need to check the latest values of https://www.extra-life.org/api/participants/X/donations every minute. But I would need to make this call for each participant/team that wants to use my app.

If we have 50 different twitch streams, I then need to make 50 calls per minute. And that's just if I'm only supporting the call to donations. At some point I'd love to post to chat when a milestone is reached (adding another call to /milestones for each participant/twitch stream), but that would put me to 100 calls per minute.

Is there a way to support requesting 2+ participant per call? Like a batch request?

Ability to display CAD or USD value of a donation

As a user, if a donation is made using CAD, I would like to be able to display the CAD value rather than the USD value.

Another option would be to expose both values and allow developers to provide display options to their users.

Webhook Spec Implementation

About

Webhooks are a great implementation for services that want to offer Fundraisees with Alerts or Notifications when donations come through. Webhooks eliminate the need for API polling, which can easily cause a buildup of web traffic when a large number of participants are being polled in an attempt to get near-instant notifications.

Streamers commonly make use of pop-up alerts from various providers that make use of Webhooks to provide as-they-happen notifications. Webhooks will make this easier for web services (that are capable of receiving HTTPS requests) to implement functionality with notifications without having to set up a process that continuously polls the API indefinitely.

Previously I've worked with Twitch, GitLab, GitHub, Patreon, IGDB, and PayPal webhooks. DonorDrive is one of the last APIs that I poll.

Twitch

A large number of Extra-Life Fundraisees seem to use Twitch as a means of reaching their audience, and the Powered by Twitch logo is present on the Extra-Life homepage. While some may use Youtube or other streaming services, I'll be referring to Twitch as an example.

Twitch conforms to the W3C WebSub Spec, and offers streamers the ability to receive near-instant POST notifications when changes are made to the results that are cached in the API. Similar functionality from DonorDrive would be extremely appreciated.

Implementation

DonorDrive does not, to my knowledge, support OAuth in any sense. Twitch Webhooks require using an OAuth token to register a webhook, while IGDB up until recently only made use of a static User-Key that was given to every developer account.

I'm not 100% if the Spec can be followed to a T, but the security around it is optimal. Prevent malicious users from creating a webhook pointed at google.com, and verify information sent to a webhook using HMAC with a user-defined key.

Personally I only use the /api/participants/{participantID}/donations endpoint for alerts, though others may be interested in other data such as team donations, or milestones.

TTL

Twitch Webhooks have a TTL of 10 days, and then must be renewed. Some of the other services' webhooks do not have a set TTL, but will disable after a limited number of non-2XX HTTP responses.

A TTL may not be necessary for DonorDrive, aside from non-2XX codes, as registrations reset every year anyway, webhooks could also do the same.

Game Day

Game Day 2020 is rapidly approaching, so I'll assume that something of this scale isn't doable this year, but may be nice to see for next year.

Unique Identifier for Donors

We have found that it is very hard to distinguish a unique donor. Would it be possible to add a field onto the Dontation API that would be a uniquely identifying field so I could tell that a donation came from a unique donor?

Our group runs a 24-hour raffle with limits on how many prizes a donor can win by tier. This is the impetus for asking for a unique donor id. Currently using DonorName isn't unique enough for our purposes.

List of features and fundraising campaigns in API documentation

I'm working on a project using the DonorDrive API for general use for all campaigns (e.g., Extra Life, Dance Marathon, NAMI, etc) in order to trigger user-customizable physical interactions. I'd like to be able to see a list of URLs and their respective available endpoints (since not all campaigns take advantage of them per the documentation) to be able to include something like a dropdown menu to select a particular campaign for a list of available options.

API Update to Show Team Information

Hello,

I'm slightly a beginner to coding and I'm not sure if this constitutes and issue, but figured I'd ask.

I'm trying to modify the Extra Life overlay which is using the DonorDrive API to view team information as opposed to it's current setup to only show single participant info.

Example URL they are using:
https://www.extra-life.org/index.cfm?fuseaction=donorDrive.streamingOverlay&eventID=543&participantID=375493&preview=true

I went into the HTML file and subbed in "participant" and the appropriate ID with "team" as well as that appropriate ID.

While this led the code to resolve it did not actually update the visual graphics. Finding this github I went through and tried to ensure the calls for Team information outlined here were in place in the HTML which they seemed to be, but it's still not pulling.

Any suggestions?

ELDonorDrive_Teams_v0.txt

Feature Request: remove 'select' attribute in favor of returning all payload values

This feature sees little use outside of the product, and the difference in payload size is relatively trivial. Removing this would streamline documentation. Ancillary benefit: knowing what fields get returned up front makes rendering the payload a lot easier.