You're on track to get doubled donations (and unlock a reward for the colleague who referred you). Keep up the great work!
Take credit for your charitable giving! Check out your tax receipts
To use your $50 gift card credits, find a project to fund and we'll automatically apply your credits at checkout. Find a classroom project
Skip to main content

We're a charity that makes it easy for anyone to help a classroom in need. Your gift is tax-deductible.

Your school email address was successfully verified.

Frequently Asked Questions

Where's the API key?

Request a key

Right now API Keys are only available to DonorsChoose partners with commitments of over $100K. If you're interested in discussing a partnership, you can reach out to our team and request an API key here.

Please include your best estimate of the daily and peak number of requests your app will make against the API for our capacity planning purposes.

Transactional features

If you need to use the transactional features, mention that in your email. Also give us some indication of how your app will use our transactions and your best estimate of the daily and peak number of transactions.

Can I query for completed projects?

Yes! See the "Completed" section of JSON Requests for details on how to query for completed projects.

Can I get reporting/analytics information on the traffic that my API usage is referring to DonorsChoose?

Our API automatically appends Google Analytics tracking codes, with your API key embedded, to all the referral URLs. So we can isolate the web traffic you send us and provide one-off reporting on it, including such metrics as: visits, donations, avg donation size, etc.

If you'd like this information, reach out to us and let us know your API key. At this time, we do not have any automated traffic/analytics reports you can access on your own.

Can I take donations on my own site and register the transaction with DonorsChoose behind-the-scenes?

In some scenarios, we can enable you to make project donations via the API. For example, you could show your site visitors classroom classroom project listings and then process the donation to a project behind-the-scenes without having to route your site visitor to DonorsChoose's front-end!

However, we're unable to make this option available to everyone. So if you're interested in using API project donations, get in touch with us so we can discuss how best to meet your needs.

If you want to dig into the technical details first, you can learn more about transactions.

Can I generate DonorsChoose gift cards using the API?
Can I get a geo-code/lat-long value for projects via the API? Can I do a geo-spatial query for projects, eg. 'bounding box' or 'point plus distance'?

Our projects are now geo-tagged: we can provide a project's lat/long coordinates in our JSON responses!

We have also enabled these types of geo-spatial queries: "bounding box," "center + distance," and "projects near me." And we added a new concise JSON response format that's useful for returning lots of points at once.

See the appropriate sections of our JSON request and JSON response documentation for details on how to employ the new geo functionality.

Can you create a publicly visible page where folks can see the projects supported via my API integration?

Yes! We've had a number of partners do this and it's a great way to tastefully showcase the impact of your API usage.

First, create a Giving Page. Then determine the Giving Page's unique identifier, which you can see as the "id" parameter in the Giving Page's public URL, eg. is Giving Page number 25298.

If you then append the parameter "&partnerID=xyzxyz" to all your API calls?where xyzxyz is your Giving Page's number?then we'll be able to associate any immediately resulting donations to your Giving Page. (You'll see that adding that parameter prompts the API to append &challengeid=xyzxyz to every project URL you get back.)

However, this form of tracking/reporting is unfortunately not super robust in that our system will lose track of the referral if the user leaves the specific project page on which they landed at DonorsChoose, browses around the site, and gives to a different project. So it should not be relied upon for audit-quality reporting.

Can I filter project listings by expiration date?

You can sort project listings to get your results in order of soonest-to-expire. However, there is currently no way to further filter project listings by expiration date.

Can I pull more than 10 projects using the RSS Feed?

You can pull up to 50 projects. Simply change the 'projects per page' count to 50, located at the bottom of the search page, and use the new url for your feed.

Is it possible to pull more project attributes via RSS than what's listed?

We've included only a few project attributes in the feed, in order to keep it concise. There is currently no way to formulate a request that adds more per-project meta-data in the feed.

Can you query for projects by their school's NCES ID?

Yes! For example, the Durant Tuuri Mott Elementary School in Flint, Michigan has the NCES ID 261452005099.

So a JSON request of this form will bring back all the projects at that school:[YOUR_API_KEY]&ncesId=261452005099

A word of warning that we do not have NCES ID numbers for every single school in our database.

Do you have any tips for using the API with PHP and AJAX?

Yes, our friend Tom authored these great notes. Thanks, Tom!

Can I integrate classroom project listings into my app on the client-side?

Yes, although you'll likely need to implement some form of JSONP in order to avoid getting an error due to the same-origin security policy. As detailed in our API Specific Parameters section, we do support using a callback function for this purpose.

You should make your callback static, as it will improve caching and in turn performance. Many AJAX frameworks will make the callback a random string unless otherwise specified so you'll be overriding that default behavior.

Also be sure to enable any caching options (eg. set the cache param to True in jQuery) or else some frameworks will append a timestamp to each JSON request to prevent caching.

How can I make JSON and other asset requests via SSL / HTTPS?

Our API supports both http and https requests. https is recommended when possible. For example, both of these URLs will work:[YOUR_API_KEY]&subject6=-6&matchingId=-1[YOUR_API_KEY]&subject6=-6&matchingId=-1

What type of identifiers are DonorsChoose's unique project IDs?

Every project on DonorsChoose has a unique ID that never changes, even after the project is completed. It will always be an integer.

Can you provide a mapping of every state, city, county, and school district's unique DonorsChoose identifier?

Since we license this data, we are unfortunately not permitted to distribute it freely.

If you have a special need for it, get in touch with us and we'll try our best to help.

Do projects show up in the completed results as soon as they are fully funded?

You can query for completed projects using the "&historical=true" API parameter as documented.

However, projects are not accessible via the API for a short period after their funding is complete while we're waiting for the teacher to confirm they still need the materials. This usually happens <24 hrs, but can take up to 3-4 days.

How do I get the '2 hours ago' time-stamp for completed projects, like I'm seeing in the front-end UX?

Our API doesn't currently provide this data, sorry!

How do I get the '6 hours left' or '3 days left' count-down time-stamps for soon-to-expire live projects, like I'm seeing in the front-end UX?

At present, we don't have the actual front-end messages available via the API.

Our front-end creates these messages at display-time by calculating the delta between the value in the expirationDate field and now.

If you want to do the same calculation, know that projects actually expire at 12:01AM Eastern of the day after the expiration date, not on the day of.

Where can I find a map of search parameters?

All search parameters currently available are listed here.

Where do I get banners, logos, one pagers, etc?