Basics
REST
The API for TheGivingLab is REST based supporting appropriate GET, POST, PUT and DELETE verbs. The API allows developers to build applications with the ability to plug-in donations to charities, allow users to create fundraising events, create and manage groups that are fundraising (work place, sports teams etc) and display information about individual fundraiser profiles (user authentication required). The sections below describe how to use the API and the data that is returned.
Authentication
In order to use the API you will need an API Key to authenticate your application. API Key can be obtained by signing up here.
Once you have received your API Key you will need to include the key in every request that is made. The API Key can be sent either in the query string or as part of the body of the request (recommended approach), for example:
https://www.thegivinglab.org/api/groups?apikey=[Your API Key]
JSON / JSONP
The API supports JSON and JSONP (for cross domain calls to GET data). When using a POST, PUT or DELETE, JSON is supported for sending parameters as part of the request body to the API. When using the API cross domain simply add the callback=? parameter to the query string to return JSONP objects.
The main objects that make up the system and are returned from the API are:
- Charity - information about a charity and their campaigns
- User - public profile data for a fundraiser and their fundraising groups and events
- Group - a fundraising group (company, sports club, school etc) or a Giving Club with details of their fundraising events / activity as well as public profile information about the group members
- Event - details about a particular fundraising event and donations made to the event
The sections below go through the API calls and the available object properties in more detail.
API Methods
Charities
The API allows developers to search our database of charities and return information about it as well as make donations to the charity.
To search for a charity you will need to make a call to the following URL with your API Key
GET https://www.thegivinglab.org/api/charities/[name or filter]
The call will generate an array of charity objects with the following properties:
Charity Object
| Property | Description |
| CharityID | The ID for the charity used by TheGivingLab.org |
| CharityName | The name of the charity |
| CharityNumber | The registered charity number |
| CharityDescription | The description of the charity activities. This is returned as HTML and may include embeddded media (video, audio or images) |
| CharityLogo | The charity logo URL |
| Address | The registered address for the charity |
| Campaigns | This is an array of campaign objects. Campaigns are specific causes or projects setup by the charity to raise funds with a target. |
| SMSCode | The SMS Code for donating to the charity via SMS |
| Website | The charity's website |
| NotFundraising | A boolean flag which if set to true indicates that the charity has chosen not allow TheGivingLab.org (or it's users) to raise money for them and therefore donations will not be taken for this charity |
To retrieve details of a specific charity (if you know the ID or the Charity Reference Number) you can also use:
GET https://www.thegivinglab.org/api/charities/charity/[ID or Charity Reference Number]
You can also get details of a specific campaign by it's ID which is returned in the Campaigns property against a Charity using the following API call.
GET https://www.thegivinglab.org/api/charities/campaign/[ID]
The call will return a JSON object with the properties below.
Campaign Object
| Property | Description |
| CampaignId | The ID for the campaign used by TheGivingLab.org |
| Name | The name of the campaign |
| Headline | The headline text for the campaign |
| Description | The description for the campaign. This is returned as HTML and may include embedded media (video, audio or images) |
| CharityLogo | The charity logo URL |
| CharityName | The name of the charity |
| ThumbnailImage | An image for the campaign (URL) |
| SMSCode | The SMS Code for donating to the campaign via SMS |
| Video | A video for the campaign. This will be a link to an MP4 video file that can be embedded using an appropriate player |
| TotalRaised | The total raised by the campaign |
| PercentageRaised | The percentage raised of the total |
| IsClosed | A boolean flag indicating that the campaign is no longer active |
| ItemDescription | A description of the item that the funds are being raised for. This will be populated when the funds raised are being used to buy a specific item or support a tangible cause (£5 to ship a bike to Namibia etc.) |
| ItemPrice | The price of the item described in the ItemDescription property |
| Updates | Updates about the campaign from the charity. Again, this is returned as HTML and may contain other media such as embedded video and images. |
Groups
Groups are a way of aggregating fundraising activity across institutions such as your work place, schools, sports clubs and other informal groups such as your friends. There are 2 types of group based fundraising supported by TheGivingLab.org:
- Group Activities - this is people fundraising as part of a group as you may do for work place giving or for your school.
- Giving Clubs - this is a new way of being able to raise money for charity by paying a fixed amount monthly (for a specified period of time) as part of a group of people to reach a larger target.
In order to search for groups and get details of their events and activities the following methods are available.
Search
Search for groups by name using the following call to our API:
GET https://www.thegivinglab.org/api/groups/[name or filter]
The call will return an array of objects with the following properties.
Group Object
| Property | Description |
| ID | The ID used by TheGivingLab.org to identify the group |
| Name | The name of the group |
| GroupOwnerID | The ID of the user that owns the group (you can use the Users API methods to retrieve details of the group owner) |
| Description | The description for the group. This is returned as HTML and may include embedded media (video, audio or images) |
| ParentGroupID | Groups are hierarchical and may be part of a larger group. Use this ID to retrieve details of the parent group |
| PictureUrl | The Url to the picture for the group |
| Target | A target amount set for the group to raise (mainly for Giving Clubs) |
| IsGivingClub | A boolean value indicating whether the group is a giving club (as described above) |
| CharityID | The ID of the charity that is supported by the group (specific to Giving Clubs) |
| CampaignID | The ID of the charity campaign that is supported by the group (specific to Giving Clubs) |
| TotalRaised | The amount raised by the group (mainly for Giving Clubs) |
| GivingClubAmount | The amount a person has to donate to join a Giving Club (for Giving Clubs only) |
| GivingClubPaymentDay | The day in the month direct debits will be collected (for Giving Clubs only) |
| GivingClubEndDate | The date the Giving Club will run until (for Giving Clubs only) |
| Events | An array of Event IDs that are associated with this group (you can use the Events API methods to get details of individual events) |
| Children | An array of child group IDs (for hierarchical groups) |
You can get details of an individual group by calling the following method:
GET https://www.thegivinglab.org/api/groups/group/[ID]
For giving clubs, you can also get a list of the members, as below.
GET https://www.thegivinglab.org/api/groups/group/[ID]/groupmembers
This will return a Group Member JSON object.
Group Member Object
| Property | Description |
| ID | The ID for the group member |
| GroupID | The ID of the group |
| User | An instance of the User object (as detailed in the Users section) with details of the member |
| DateJoined | The date they joined group |
| DateLeft | The date they left group |
| DateLastDirectDebitPaid | The date when the last direct debit payment was taken (this is only available when the current user is authenticated and is the owner of the group. For user authentication see the Users API methods) |
As well as being able to retrieve data about groups and group members you can also create / update groups and add / remove group members (in case of Giving Clubs) using the following POST, PUT and DELETE method calls:
POST https://www.thegivinglab.org/api/groups/group/
With a request body that passed through the Group JSON object as follows:
{
"Name": "My Giving Club",
"Description": "My friends and I want to make a difference!",
...
}
To update an existing group use:
PUT https://www.thegivinglab.org/api/groups/group/
With a request body that passed through the Group JSON object as follows:
{
"ID": "cd21db7f-8c0f-409c-ae89-595caf2848f3",
"Name": "The Best Giving Club EVER!",
"Description": "My friends have made a difference!",
...
}
For Giving Clubs, you can remove members from your club (as long as you are authenticated and the owner)
DELETE https://www.thegivinglab.org/api/groups/groupmember/[Group Member ID]
Group Activity
To get an aggregated feed of all activity across a group (donations, new events, completed events etc.) call the method below.
GET https://www.thegivinglab.org/api/groups/group/[ID]/activity/
With the request body with the following parameters
{
"apikey": "cd21db7f-8c0f-409c-ae89-595caf2848f3",
"DateFrom": "[Date and time to filter from]",
"DateTo": "[Date and time to filter to]",
}
This will return an array of Activity objects ordered by time (descending). Note - if you don't specify the DateFrom and DateTo parameters, the activity for the last month will be returned.
Activity Object
| Property | Description |
| ActivityType | The activity type - "Event", "EventDonation", "GroupMember" |
| ActivityTime | The date and time of when the activity occurred |
| ActivityTypeID | The ID of the associated object - "Event", "GroupMember" (for "EventDonation", the ID of the associated "Event" will be returned) |
| Description | The description of the activity |
| AssociatedImageUrl | An associated image (of the event or group member) |
Users
Similar to groups, you can search for users and get details of their public profile and events. You can also use the API to create apps that allow users to create a profile with TheGivingLab.org (using Facebook Connect) as well as allowing them to sign into their existing profile and view / update any of their events.
To search for a user you simply need to call the following API method:
GET https://www.thegivinglab.org/api/users/[name or filter]
This returns an array of matching User objects
User Object
| Property | Description |
| ID | The ID for the User |
| Forename | The user's forename |
| Surname | User's surname |
| EmailAddress | The user's email address (only available once they have authenticated) |
| Tag | The user's unique Url identifier for their profile on TheGivingLab.org site. |
| FacebookID | The user's FacebookID (only available once they have authenticated) |
| ProfilePictureUrl | A Url to the user's profile picture |
| TotalRaised | The total amount raised by the user |
| TotalDonated | The total amount donated by the user (only available once they have authenticated) |
| Events | An array of Event IDs that the user has setup. You can use the Events API methods to get details of the individual events and donations |
| Groups | An array of Group IDs that the user has created or is part of (if a Giving Club). You can use the Groups API methods to get details of the individual groups |
| Bio | Information about the user |
If you know the ID for a user you can get the profile by calling the following method:
GET https://www.thegivinglab.org/api/users/user/[ID]
This will return a single instance of the User object.
User Authentication & Sign Up
We use Facebook Connect as a method for authenticating users as well as making it easy for them to sign up. If you wish to create an app that allows users to authenticate and interact with their account via your app then you will need to setup your app to allow Facebook to authenticate users (instructions here - https://developers.facebook.com/docs/reference/javascript/FB.login/).
Once you have your app setup and it is returning the Facebook Access Token for the current user, you authenticate them by calling the following method.
POST https://www.thegivinglab.org/api/users/authenticate
With the following request body
{
"apikey": "[Your API Key]",
"FacebookToken": "[Facebook Access Token]"
}
Note: When using Facebook authentication in your app, you will need to ask for Email permission as a minimum in order for the API to validate the Token from Facebook.
If authentication is successful you will be returned a user object with details of the authenticated user if they exist on the system.
You can also allow users to Sign Up to TheGivingLab.org using Facebook Connect. Once you have the Facebook Access Token after authenticating with Facebook, you can call the following method to create the profile on TheGivingLab.org:
POST https://www.thegivinglab.org/api/users/createuser
With the following request body
{
"apikey": "[Your API Key]",
"FacebookAccessToken": "[Facebook Access Token]"
}
Once the profile has been created, you will be returned a user object with the user's details
As well as using Facebook Connect to add users, you can also add / create users by asking them for their name, email address and password. In order to create a user directly on TheGivingLab.org you can call the following method:
POST https://www.thegivinglab.org/api/users/registeruser
With the following request body
{
"apikey": "[Your API Key]",
"Forename": "Stephan"
"Surname": "El Shaarawy"
"Email": "Stephan@hisdomain.com"
"Password": "[Password Selected by User]"
}
Once the profile has been created, you will be returned a user object with the user's details
User Activity
To get an aggregated feed of all activity for a user (donations, new events, completed events etc.) call the method below.
GET https://www.thegivinglab.org/api/users/user/[ID]/activity/
With the request body with the following parameters
{
"apikey": "cd21db7f-8c0f-409c-ae89-595caf2848f3",
"DateFrom": "[Date and time to filter from]",
"DateTo": "[Date and time to filter to]",
}
This will return an array of Activity objects (as described in the Groups section ordered by time (descending). Note - if you don't specify the DateFrom and DateTo parameters, the activity for the last month will be returned.
Events
Our Events API methods allow your apps to be able to retrieve information about specific fundraising events being run by a user or group. The event will include details about the charity and the donations made via the event.
To get details of an event that is owned by a user or group, call the following method.
GET https://www.thegivinglab.org/api/events/event/[ID]
This will return an Event object.
Event Object
| Property | Description |
| ID | The ID for the Event |
| Name | The event name |
| SMSCode | The SMS Code for donating to the event via SMS |
| TargetAmount | The target amount to be raised by the event |
| TotalRaised | The amount raised so far |
| EventDate | The date of the actual event / activity for the fundraiser (for example, running a marathon or cake sale etc.) |
| StartDate | The date to start fundraising (usually the day the event is created) |
| CloseDate | The day the event is completed and no more donations can be taken |
| Ended | A boolean flag to indicate whether the event is now complete / ended |
| CampaignID | The ID of the campaign the event is fundraising for - if the event is fundraising directly for a charity this will be null |
| CharityID | The ID of the charity the event is fundraising for |
| OwningUserID | The ID of the user that setup the event |
| OwningGroupID | The ID of the group that the event is linked to (this may be null if the event is being run by an individual user only) |
| EventPictureUrl | The Url to the image representing the event |
| EventDonations | An array of EventDonation objects providing details of each donation made to the event |
Event Donation Object
| Property | Description |
| DonorName | The name of the donor |
| Message | The message left by the donor (auto generated if donor chose not to leave a message) |
| DonationAmount | The amount donated |
| GiftAidAmount | The amount of Gift Aid added to the donation if the donor opted to claim Gift Aid |
| GiftAidIncluded | A boolean flag indicating whether Gift Aid was claimed |
| EventID | The ID of the event the donation is related to |
| DonationDate | The date the donation was made |
| UserID | The ID of the user (if the donor was an existing user in the system with a profile, otherwise it is null) |
Users authenticated using User Authentication API methods can create and update events by calling the following methods.
POST https://www.thegivinglab.org/api/events/event/
With the request body containing a new Event object populated with the required parameters
{
"apikey": "cd21db7f-8c0f-409c-ae89-595caf2848f3",
"Name": "Running to Brighton",
"Description": "I'm running from London to Brighton to raise funds for Ace Africa!",
"Target": "1000",
"CharityID": "dg21db7f-8c5f-669c-ae89-785caf2848f3",
"EventDate": "18 September 2012",
...
}
You can also set the OwningGroupID field with ID of a group if you want the event to be part of a group. Once the event is created you will be returned a copy of the Event object with the ID and SMS Code populated (along with other system generated fields).
In order to update an existing event you call the above method in the same way but use PUT instead.
PUT https://www.thegivinglab.org/api/events/event/
With the request body containing a new Event object populated with the required parameters
{
"apikey": "cd21db7f-8c0f-409c-ae89-595caf2848f3",
"ID": "[ID of the event]",
"Name": "Running to Brighton",
"Description": "I'm running from London to Brighton to raise funds for Ace Africa! Woohoo!",
"Target": "2000",
"CharityID": "dg21db7f-8c5f-669c-ae89-785caf2848f3",
"EventDate": "18 September 2012",
...
}
Donate
TheGivingLab.org allows you to build donation apps for single credit / debit card donations, direct debit donations (for Giving Clubs only) and SMS donations. Donations are processed by our payment providers and users will be directed to those payment pages via a browser.
Credit / Debit / PayPal Donation
To allow users to make a single donation using their credit / debit card or PayPal account, simply redirect or form POST the user to the following URL in the browser:
https://www.thegivinglab.org/api/donation/start
Passing the following parameters either in the query string or in the request body (as a form)
| Property | Description |
| DonationType | This should always be 0 for card payments |
| DonorID | User ID if current user has profile |
| EventID | The ID for an event if donation is for an event |
| CampaignID | The ID for a charity campaign if donation is for a campaign |
| CharityID | The ID for a charity if donation is for a charity only |
| Message | Message left by the user if donating to a friend's event |
| ReturnUrl | The URL of the page to return users once they have donated |
An example donation call with a new user (no existing profile) donating to a charity would look like
https://www.thegivinglab.org/api/donation/start?donationtype=0&amount=10&charityid=84ed3c54-6d8c-41c5-8090-f8ec800f45a7&returnurl=http://www.mywebsite.com/
Once users have donated the system will return them to the URL specified in the returnurl parameter.
Direct Debit Donations for Giving Clubs
To allow users to join a Giving Club and setup their direct debit, simply redirect or form POST the user to the following URL in the browser:
https://www.thegivinglab.org/api/donation/start
Passing the following parameters either in the query string or in the request body (as a form)
| Property | Description |
| DonationType | This should always be 1 for a monthly direct debit and 3 for an annual direct debit |
| DonorID | User ID if current user has profile |
| GroupID | The ID for the group the user wants to join |
| ReturnUrl | The URL of the page to return users once they have donated |
An example donation call with a new user joining a group would look like
https://www.thegivinglab.org/api/donation/start?donationtype=1&groupid=84ed3c54-6d8c-41c5-8090-f8ec800f45a7&returnurl=http://www.mywebsite.com/
Once users have donated the system will return them to the URL specified in the returnurl parameter.
SMS Donations
Users can also donate via SMS where an SMS code is available against a Charity, Campaign or an Event. Users can donate £1.50, £3.00, £5.00 or £10.00 by simply texting GIVE [Amount] [SMS Code] to 70707. For example, a £3 donation to a friend's fund raising event would like:
GIVE 3 FOX1
Where FOX1 is the SMS code for my friend's event.
Note: All SMS messages should go 70707 and must include GIVE at the start of the message.
App Stores
The guidelines for apps that you wish to distribute via an app store (Apple iTunes, Google Play, Windows App Store) are as follows:
- Free apps can be distributed by the developer as long as all donations are processed via our web donation channel.
- Any donations where the app is not free and the cost of the app is to form part or all of the donation, the app must be distributed under the See The Difference app store accounts for Apple iTunes, Google Play and Windows App Store.
- All paid for apps must decide on the charity that they wish all or part of the purchase revenue to be donated to upfront before the app is published to the relevant app stores.
- Apps that are free and wish to use the API / web donation channel can select the charity they wish to donate to at the point of transaction in app.
- At the moment, we do not accommodate for apps that allow users to purchase credit to be spent in game at later date. If developers do wish to use credits, they need to allow the user to pick a charity the funds will be donated to at the point the credits are purchased.
Mobile App Skeleton / Framework - Give As You Go
One of our contributors, Florian Rathgeber, has setup a mobile app skeleton built on spine.mobile using the TheGivingLab API. The app comes with authentication, sign up and sign in out of the box and is intended to serve as a starting point for anyone building mobile apps using TheGivingLab API. You can view the project and source code on GitHub.
Features
- Sign up with name, email and password
- Sign up via facebook
- Sign in with email and password
- Sign in via facebook
- Show the users profile
- HTML5 local storage for persistent sessions across app restart
