Fundraiser API

by Scott Dilley - CTO 12 Jun 2021

This article provides information on how to connect to the Fundraiser API. This API is not designed for use with a CRM; to access your data for importing into a CRM, please view our standard API documentation.

What is it?

The Fundraiser API allows you to access data on behalf of your fundraisers, essentially mimicking what they can see and do on the website. This is designed to be used for things like Mobile App development.

What are the benefits?

The Fundraiser API is designed to allow sites access to fundraiser-specific data via RESTful requests and to also allow some limited ability for updating records. This API will not allow for more triggered requests such as processing payments or sending out tax receipts.
All endpoints will return JSON.

Key terms:

API: stands for application programming interface, which is a software intermediary that allows two applications to talk to each other using a set of definitions and protocols.

CRM: stands for stands for customer relationship management, which, as the name suggests, is used for managing your relationships with customers.

JSON: stands for JavaScript Object Notation, which is a format used for storing and transporting data.

Limits

API query requests are not limited since you will be querying your own data on your own instance. Therefore, we leave the responsibility of limiting the number and frequency of requests up to each client; however, data returned via this API will be cached for a period of up to 15 minutes, depending on what data is being requested.

Accessing the API

Accessing the Fundraiser API is done via standard http calls using the language of your choice. Any connection must be made by an authenticated admin user which can be administered via the standard admin console.

Creating a User

To connect to your API first, you need to create a user and allow that user access to the API. This can be done in Funraisin platform by going to Accounts > New User. Jump in and create a new user and make sure you tick the “API Access” checkbox and then keep these credentials handy. You will also be able to retrieve the user's API key at this stage for use later on.

Make sure when creating a user that you allow access to the Fundraiser API only.

Click to expand

Your API URL

To access your API, you can use https://yourdomain.com/api/.

Authentication

When connecting to your API, you need to send through an API key for the user that you created in the step above. This can be done either using an Authentication header or via simple GET variable "apikey"; however, given that the use of this API is considered to be more open to the public (e.g., a mobile app), we strongly suggest using the header authentication method once your application is live.

For example:

curl -H "Authorization: Bearer [APIKey]" "https://yourdomain.como/api/"

Or for testing:

https://yourdomain.com/api/?apikey=[APIkey]

Data Handling

Some endpoints will allow you to update or create new records by posting an array called “data” to the endpoint.

Example: POST to https://yourdomain.com/api/fundraiser_login

data[login_email] = joeblogs@gmail.com;
data[login_password] = mypassword;

Will attempt to login as the fundraiser Joe Blogs.

Curl example

curl -H "Authentication: bearer MYAPIKEY" -d "data[login_email]=joeblogs@gmail.com&data[login_password]=mypassword" "https://domain.com/api/fundraiser_login"

Some endpoints will allow for filtering and ordering of data; this can be done via standard GET variables, and these will be listed against the endpoints that support it.

Responses

Valid responses will return an http status of 200 along with the JSON payload. Each response will have a "results" parameter indicating how many records are available, and the actual data returned will also be encapsulated in an object called "data."

"results":1, "data":{ "first_name" => "joe", "last_name" => "blogs", "email" => "joe@domain.com" }

Errors

Any errors encountered will return an http status of 403 along with a description of the error encountered.

"error":1, "errormessage":"Unable to find matching record"

Pagination

Some endpoints cater to many records, so when this is the case, you will be able to paginate through the data using a GET variable "offset." By default, the records will be limited to 50 records at a time, and when pagination is available, you will see the attributes "nextpage" and "prevpage" in the response payload, which will automatically calculate the correct offset for you.

"nextpage":"https://www.domain.com/api/endpoint/100", "prevpage":"https://www.domain.com/api/endpoint/50"

Endpoints

Get Profile

Get Team Profile

Get Participant's Events

Event Leaderboards

Event Team Leaderboards

Get Event Participants

Get Event Teams

Get Team Members

Get Event Organisations

Get Organisation Members

Get Fitness Activities

Update Fitness Activity

Delete Fitness Activity

Login

Allows you to login as a fundraiser to retrieve a token that can then be used for any future call.

Url: https://yourdomain.com/api/fundraiser_login
POST variables: login_email and login_password

Request

"data" = array( "login_email", "login_password" );

Curl example

curl -H "Authorization: bearer MYAPIKEY" -d "data[login_email]=joeblogs@gmail.com&data[login_password]=mypassword" "https://domain.com/api/fundraiser_login"

Response

"results":1, "data" : { "member_id":1234, "token":"unique string",// save for calls to other endpoints "first_name":"First Name", "last_name":"Last Name", "email":"Email Address", "page_url":"URL to Fundraising Page", "photo_url":"URL to profile pic", "phone_home":"Home Phone Number", "phone_work":"Work Phone Number", "mobile":"Mobile Phone Number", "postcode":"Postcode", "state":"State", "country":"Country", "events":"Number of Active Pages", "recent_event_id" : "ID of Most Recent Event",// save for calls to other endpoints "total_raised":"Total Amount Raised", "last_updated":"Date Last Updated", "date_created":"Date Created", }

Of the data returned the 2 most important fields are "token" and "recent_event_id" as these 2 values will be required to access other endpoints such as this person's profile.

The "recent_event_id" is the ID of the participant's most recent Active event and in most cases the participant will only have a single event unless they are on a platform that is running DIY events as well as P2P events.

If the participant has more than 1 "events" then you can make a call to Get Participant's Events below to loop through the current events that thay are in.