<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head><title> </title><link rel="stylesheet" type="text/css" href="/Content/docs.css" /><link href="/Content/syntaxhighlighter_3.0.83/styles/shCore.css" rel="stylesheet" type="text/css" /><link href="/Content/syntaxhighlighter_3.0.83/styles/shThemeDefault.css" rel="stylesheet" type="text/css" /> <script type="text/javascript" src="/content/syntaxhighlighter_3.0.83/scripts/shCore.js"></script> <script type="text/javascript" src="/content/syntaxhighlighter_3.0.83/scripts/shAutoloader.js"></script> <script type="text/javascript" src="/content/jquery-1.6.1.min.js"></script> </head> <body style="background-color: #F2F2F2"> <div> <div style="background-color: #78256D; margin-left: auto; margin-right: auto; width: 900px; height: 30px; padding: 10px 0px 10px 0px;"> <div style="padding: 5px 10px 10px 25px; color: White; font-weight: bolder; font-size: 18px;">JustGiving API Documentation</div> </div> <div style="background-color: #FFFFFF; margin-left: auto; margin-right: auto; width: 900px; padding: 10px 0px 0px 0px; height: 100%; min-height: 1000px;"> <div style="padding: 10px 0px 0px 25px; float: left; width: 130px;"> <h2>Getting Started</h2> <h1><a href="/docs">First Steps</a></h1> <h2>Resources</h2> <a href="/docs/resources/v1/CustomCodes">CustomCodes</a><br /> <a href="/docs/resources/v1/PagesCreated">PagesCreated</a><br /> <a href="/docs/resources/v1/Payment">Payment</a><br /> <h2>Using the API</h2> <a href="/docs/usage">Usage</a><br /> <a href="/docs/usage#gettingAccess">Getting Access</a><br /> <a href="/docs/usage#terminology">Terminology</a><br /> <a href="/docs/usage#api-keys">API Keys</a><br /> <a href="/docs/usage#contentTypes">Content Types</a><br /> <a href="/docs/usage#httpVerbs">HTTP Verbs</a><br /> <a href="/docs/usage#statusCodes">Status Codes</a><br /> <a href="/docs/usage#errors">Errors</a><br /> <a href="/docs/usage#protectedResources">Security</a><br /> <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">What is REST?</a><br /> <h2>API Keys</h2> <a href="https://developer.justgiving.com">API Key Portal</a><br /> </div> <div style="padding: 10px 25px 0px 0px; float: right; width: 700px;"> <div> <h2>Using the API</h2> <h3 id="gettingAccess">Getting Access</h3> <p>You need a JustGiving API key to access both our staging and production servers. You can apply for, and recieve one instantly, by using <a href="https://developer.justgiving.com/signup">our API registration form</a>.</p> <h3 id="terminology">Conventions</h3> <p>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.</p> <h3 id="api-keys">API Keys</h3> <p>Once you've generated an API key using the <a href="https://developer.justgiving.com/">developer.justgiving.com</a> portal, you'll need to use it in requests you make.</p> <p>We support two methods of supply the API key. You'll notice in all of the documentation pages, we supply an example Url at the very top of the documentation in the format <b>/{apiKey}/v1/fundraising/pages/{pageShortName}</b>.</p> <p>You must either supply your API key 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 <b>/v1/fundraising/pages/{pageShortName}</b>.</p> <p>Over time we intend to transition to the "API key in header" model, but for compatability with existing clients both schemes are supported. We'd suggest prefering "API key in header" for slightly more logical Urls.</p> <h3 id="contentTypes">Content Types</h3> <p>We support Json, XML, JsonP (with a callback= query string parameter), Comma-separated value (CSV) and native MS Excel. 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.</p> <p>In some cases, we've found some frameworks require your XML to be ordered alphabetically, so if you're struggle to use XML, first try Json, then check your ordering.</p> <h3 id="httpVerbs">Http Verbs</h3> <p>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.</p> <h3 id="statusCodes">Status Codes</h3> <p>The API makes use of HTTP status codes as per-spec.</p> <p>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 worse of cases "500 Internal Server Error".</p> <h3 id="errors">Errors</h3> <p>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. Below is an example of a error response when a incorrect Application ID is supplied.</p> <p> <pre class="brush: js"><errors xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <error> <id>appIdNotFound</id> <desc>Supplied Application ID not found access is forbidden.</desc> </error> </errors> </pre> </p> <h3 id="protectedResources">Protected Resources</h3> <p>Most methods require Authentication, the method documentation details whether Authentication is required. You are providing a username and password of a JustGiving <strong>charity</strong> user, this shouldn t be confused with a front-facing JustGiving.com user account, or with the Application ID which you provide in the URL.</p> <p>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.</p> <p>Further information <a href="http://tools.ietf.org/html/rfc2617#section-2">http://tools.ietf.org/html/rfc2617#section-2</a></p> </div> <div> </div> </div> <div style="clear: both;"></div> </div> </div> <script type="text/javascript"> SyntaxHighlighter.autoloader( 'js jscript javascript /content/syntaxhighlighter_3.0.83/scripts/shBrushJScript.js', 'xml /content/syntaxhighlighter_3.0.83/scripts/shBrushXml.js'); SyntaxHighlighter.all(); </script> </body> </html>