JustGiving API

Environments

All the URIs provided in this documentation are environment independent.

While developing against our staging environment you should use api.staging.justgiving.com. In production use api.justgiving.com

The staging environment is always running the version of JustGiving that is currently on production.

When you register for an API AppID, you'll be able to access the staging and production environments immediately.

Terminology and Conventions

We only use a handful of common terms and conventions for the data made available over the API.

Unless otherwise stated anything called an Id (pageId, eventId, charityId) is the JustGiving Id, and is a 32-bit integer.
PageUrl, PageShortName and PageId; for a given Url of http://www.justgiving.com/my-page, the page Url is the entire string, the PageShortName is "my-page" and the PageId is the JustGiving Id for that page.

When supplying parameters to the API, you will be required to supply data in a combination of the Url called, the body of the request, and some optional query string parameters. By convention anything listed as part of the Url is required, the request body requirements will be outlined on a case by case basis, and any parameters listed but not appearing in either the Url example or the request body should be presumed optional. If you wish to supply these values they should be added as query string parameters.

AppId

Once you've generated an API appID (sometimes known as an API key), you'll need to use it in requests you make.

You'll notice in all of the documentation pages, we supply an example Url at the very top of the documentation in the format /{appId}/v1/fundraising/pages/{pageShortName}.

You must either supply your API AppID in the Url requested here, or, include it as a HTTP header called "x-api-key". If you choose to use the header, you can access the exact same API method using the Url /v1/fundraising/pages/{pageShortName}.

Over time we intend to transition to the "API AppID in header" model, but for compatability with existing clients both schemes are supported. We'd suggest prefering "API AppID in header" for slightly more logical Urls.

Content Types

We support Json, XML and experimentally JsonP (with a callback= query string parameter). You must ensure you set your HTTP headers correctly (Content-type and Accept) while making requests to ensure that we understand your requests and can respond accordingly.

In some cases, we've found some frameworks require your XML to be ordered alphabetically, so if you've struggled to use XML, first try Json, then check your ordering.

You should always use the Accept header in your request to specify which type of content you want to receive in the response:

Http Verbs

We use standard HTTP verbs for our requests. Expect to see resources that require GET, HEAD, POST and PUT to work correctly. Ensure your framework supports these verbs.

Status Codes

The API makes use of HTTP status codes as per-spec.

The kind of responses you might recieve are, "200 OK", "201 Created", "400 Bad Request" (for validation errors), "401 Unauthorized" (authentication errors), "403 Forbidden" (application Id errors), "404 Not Found" (if a resource is not found), "409 Conflict" (when you're trying to create a resource which already exists), and in the worst of cases "500 Internal Server Error".

Errors

If there is an error, in addition to Status Codes the response will contain a collection of errors. Specific errors for each method are detailed in the method documentation.

Protected Resources

Some methods require Authentication, the method documentation details whether Authentication is required. You are providing a username and password of a JustGiving user, this shouldn’t be confused with providing a Application ID in the URL.

The Authentication used by the JustGiving API is known as “Basic Authentication”. This means that a username and password are Base64 encoded and sent as part of the HTTP header as raw text. The API uses SSL so these details will remain secure. Each request that requires Authentication will require the Authentication header to be included.

Our methods are secured in three categories, "Authentication required" which require a valid basic auth header to access, "Authentication not required" where regardless of basic auth header, the resource you're requesting is available, and "Optional" where you may get different data from a resource if you supply authentication credentials which indicate ownership.

A good example of the "Optional" authentication model is our Donation API, which will return exactly the same data as the JustGiving website if you're not authenticated, however if you authenticate as the page owner, any data which is disabled from view on the web (donation amounts, real names) will become visible over the API, much like when you view your page in your end user account.

Testing your application

Once you sign up you will automatically have access to our staging and production environments.

All testing should be done against the staging environment only. The test environments run against a test payment provider.

To make things easier, you can use the following test card against the system and your test donations should validate

Visa Credit Card
4111 1111 1111 1111
Any valid looking expiry date / start date /
CV2 code = 100
Enter 1234 to pass the card verification step

Documentation