Fundraiser API

by Scott Dilley - CTO 12 Jun 2021

Overview

This article provides information on how to connect to the Fundraiser API, this API allows you to access data on behalf of your fundraisers essentially mimicking what they can see and do on the website and it is designed to be used for things like Mobile App development. 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.

Technology

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

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 howver 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 > User Admin. 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.

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 a http status of 200 along with the JSON payload. Each response will have a "results" parameter indicating how many records are available, and the data actual 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 a http status of 403 along with a description of the error encountered

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

Pagination

Some endpoints cater for 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 aill automatically calculate the correct offset for you.

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

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 "Authentication: 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.

Get Profile

Allows you to access a specific fundraiser's profile. If you pass through the Event ID from the previous Login call then this will allow you to access their fundraising profile for the specific event, otherwise a more generic response will be returned similar to the Login endpoint.

Url: https://yourdomain.com/api/fundraiser_profile//{EventID} (opt)

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_profile/1234-5678-9012/123"

Response

"results" : 1,
"data" : {
  "member_id":1234,
  "token":"1234-5678-9012",
  "first_name":"Joe",
  "last_name":"Blogs",
  "email":"joe@gmail.com",
  "page_url":"https://www.domain.com/fundraiser/joeblogs",
  "photo_url":"URL to profile pic",
  "phone_home":"02 8099 1234",
  "phone_work":"02 8019 5432",
  "mobile":"+61405123456",
  "postcode":"2026",
  "state":"NSW",
  "country":"Australia",
  "events":"2",
  "recent_event_id" : "123",
  "total_raised":"250",
  "fundraising_target" : 1000,
  "steps_target" : 20000,
  "distance_target" : 0,
  "duration_target" : 0,
  "total_activities" : 9,
  "total_distance" : 0,
  "total_steps" : 1000,
  "total_duration" : 0,
  "team":{
    "team_id": 123,
    "name":"Joes Team",
    "photo_url":"https://www.domain.com/path-to-photo",
    "page_url":"https://www.domain.com/fundraiser/joesteam",
  },
  "organisation":{
    "org_id":5436,
    "name":"Funraisin",
    "photo_url":"https://www.domain.com/path-to-photo",
    "page_url":"https://www.domain.com/fundraiser/funraisin",
  },
  "donations":[{
    "name":"Joes Mum",
    "amount":30,
    "comments":"Good Luck!",
    "photo":"https://www.domain.com/path-to-photo",
    "sent_thanks":"Y",
    "date_created":"2021-04-31 12:14:46"
  }]
  "last_updated":"2021-04-01 10:05:56",
  "date_created":"2021-03-29 10:45:13",
}

Get Team Profile

Allows you to access a specific team's profile

Url: https://yourdomain.com/api/fundraiser_team_profile/{TeamID}

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_team_profile/1234"

Response

"results" : 1,
"data" : {
  "team_id":1234,
  "name":"Joes Team",
  "page_url":"https://www.domain.com/fundraiser/joesteam",
  "photo_url":"URL to team profile pic",
  "total_raised":"250",
  "fundraising_target":5000,
  "total_activities" : 9,
  "total_distance" : 0,
  "total_steps" : 1000,
  "total_duration" : 0,
  "donations":[{
    "name":"Joes Mum",
    "amount":30,
    "comments":"Good Luck!",
    "photo":"https://www.domain.com/path-to-photo",
    "sent_thanks":"Y",
    "date_created":"2021-04-31 12:14:46"
  }],
  "members":[{
    "name": "jenny blogs",
    "total_raised": 130,
    "photo_url": "https://www.domain.com/path-to-photo",
    "fundraising_target": 1000,
    "page_url": "https://www.domain.com/fundraisers/jennyblogs",
  }],
  "last_updated":"2021-04-01 10:05:56",
  "date_created":"2021-03-29 10:45:13",
}

Get Participant's Events

Returns a list of current events (fundraising pages) for a specific fundraiser

Url: https://yourdomain.com/api/fundraiser_events/

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_events/1234-5678-9012"

Response

"results" : 23,
"data" : {
 "events":[{
  "event_id":"1234",
  "event_name":"Steptember2021",
  "event_code":"step2021",
  "date_registered":"2021-05-22 04:32:21",
  "page_url":"https://www.domain.com/fundraiser/joeblogs/steptember",
  "total_raised":250,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  },
  {"event_id":"2345",
  "event_name":"Joe's Big BBQ",
  "event_code":"JBBQ",
  "date_registered":"2021-05-25 03:52:34",
  "page_url":"https://www.domain.com/fundraiser/joeblogs/joesbigbbq",
  "total_raised":"15.00",
  "total_distance":0,
  "total_steps":0,
  "total_duration":0
  }]
}

Get Event Participants

Returns a list of fundraisers within a specific event.

Url: https://yourdomain.com/api/fundraiser_individuals/{EventID}/
Cache Time: 5mins

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_individuals/1234"

Response

"data":{
 "participants":[{
  "first_name":"Joe",
  "last_name":"Blogs",
  "page_url":"https://www.domain.com/fundraiser/joeblogs/ourevent",
  "photo_url":"https://www.domain.com/path-to-photo",
  "total_raised":250,
  "fundraising_target":1000,
  "total_distance":0,//miles or kms
  "distance_target":1000,
  "total_steps":1000,
  "steps_target":10000,
  "total_duration":0,//hours
  "duration_target":20000
  },
  {"first_name":"Mary",
  "last_name":"Ann",
  "page_url":"https://www.domain.com/fundraiser/maryann/ourevent",
  "photo_url":"https://www.domain.com/path-to-photo",
  "total_raised":250,
  "fundraising_target":1000,
  "total_distance":0,
  "distance_target":1000,
  "total_steps":1000,
  "steps_target":10000,
  "total_duration":0,
  "duration_target":20000
  }]
},
"results":250,
"nextpage":"https://www.domain.com/api/fundraiser_individuals/{EventID}/{offset+50}",
"prevpage":"https://www.domain.com/api/fundraiser_individuals/{EventID}/{offset-50}"

Responses are limited to 50 records per call

Get Event Teams

Returns a list of teams within a specific event

Url: https://yourdomain.com/api/fundraiser_teams/{EventID}/

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_teams/1234"

Response

"data":{
 "teams":[{
  "name":"The Go Betweens",
  "page_url":"https://www.domain.com/fundraiser/thegobetweens",
  "total_raised":3910,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  },
  {"name":"Twisted Sisters",
  "page_url":"https://www.domain.com/fundraiser/Twistedsisters",
  "total_raised":2500,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  }]
},
"results":200

Get Team Members

Returns a list of fundraisers within a specific team

Url: https://yourdomain.com/api/fundraiser_team_members/{TeamID}/

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_team_members/53436"

Response

"data":{
 "participants":[{
  "first_name":"Joe",
  "last_name":"Blogs",
  "page_url":"https://www.domain.com/fundraiser/joeblogs/ourevent",
  "total_raised":250,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  },
  {"first_name":"Mary",
  "last_name":"Ann",
  "page_url":"https://www.domain.com/fundraiser/maryann/ourevent",
  "total_raised":250,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  }]
},
"results":2

Get Event Organisations

Returns a list of organisations within a specific event

Url: https://yourdomain.com/api/fundraiser_organisations/{EventID}/

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_organisations/1234"

Response

"data":{
 "organisations":[{
  "name":"Jims Plumbing",
  "page_url":"https://www.domain.com/fundraiser/jimsplumbing",
  "total_raised":3910,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  },
  {"name":"Qantas",
  "page_url":"https://www.domain.com/fundraiser/qantas",
  "total_raised":2500,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  }]
},
"results":200

Get Organisation Members

Returns a list of fundraisers within a specific organisation

Url: https://yourdomain.com/api/fundraiser_organisation_members/{TeamID}/

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_organisation_members/53436"

Response

"data":{
 "participants":[{
  "first_name":"Joe",
  "last_name":"Blogs",
  "page_url":"https://www.domain.com/fundraiser/joeblogs/ourevent",
  "total_raised":250,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  },
  {"first_name":"Mary",
  "last_name":"Ann",
  "page_url":"https://www.domain.com/fundraiser/maryann/ourevent",
  "total_raised":250,
  "total_distance":0,
  "total_steps":1000,
  "total_duration":0
  }]
},
"results":2

Get Event Leaderboards

Returns a leaderboard of fundraisers within a specific event

Url: https://yourdomain.com/api/fundraiser_leaderboard/{EventID}/{LeaderboardType}/

{LeaderboardType} Options: fundraising, steps, distance, duration

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_leaderboard/123/fundraising"

Response

"data":{
 "leaderboard":[{
  "name":"Joe Blogs",
  "photo_url":"https://www.domain.com/path-to-photo",
  "page_url":"https://www.domain.com/fundraiser/joeblogs/ourevent",
  "total_raised":250,
  "fundraising_target":1000,
  "rank": 1,
  "total_distance":0,
  "distance_target":1000,
  "total_steps":1000,
  "steps_target":10000,
  "total_duration":0,
  "duration_target":20000
  },
  {"name":"Mary Ann",
  "page_url":"https://www.domain.com/fundraiser/maryann/ourevent",
  "photo_url":"https://www.domain.com/path-to-photo",
  "total_raised":230,
  "fundraising_target":1000,
  "rank":2,
  "total_distance":0,
  "distance_target":1000,
  "total_steps":1000,
  "steps_target":10000,
  "total_duration":0,
  "duration_target":20000
  }]
},
"results":290,
"nextpage":"https://www.domain.com/api/fundraiser_leaderboard/{LeaderboardType}/{EventID}/{offset+50}"

Note that the fields returned will depend on the leaderboard type. For example for a fundraising leaderboard no fitness data will be returned.

Get Event Team Leaderboards

Returns a leaderboard of teams within a specific event

Url: https://yourdomain.com/api/fundraiser_team_leaderboard/{EventID}/{LeaderboardType}/

{LeaderboardType} Options: fundraising, steps, distance, duration

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_team_leaderboard/123/fundraising"

Response

"data":{
 "leaderboard":[{
  "name":"Joe's Team",
  "page_url":"https://www.domain.com/fundraiser/joesteam",
  "total_raised":250,
  "fundraising_target":1000,
  "rank": 1,
  "total_distance":0,
  "distance_target":1000,
  "total_steps":1000,
  "steps_target":10000,
  "total_duration":0,
  "duration_target":20000
  },
  {"name":"Mary's Team",
  "page_url":"https://www.domain.com/fundraiser/marysteam",
  "total_raised":230,
  "fundraising_target":1000,
  "rank":2,
  "total_distance":0,
  "distance_target":1000,
  "total_steps":1000,
  "steps_target":10000,
  "total_duration":0,
  "duration_target":20000
  }]
},
"results":2

Get Participant's Fitness Activities

Returns a list of fitness activities for an individual

Url: https://yourdomain.com/api/fundraiser_activities//{EventID}

Curl example

curl -H "Authentication: bearer MYAPIKEY"  "https://domain.com/api/fundraiser_activities/1234-5678-9876-6543/123"

Response

"data":{
 "activities":[{
  "id":1234,
  "name":"Morning Run",
  "type":"Ride",
  "source":"Strava",
  "distance":0,
  "distance_target":1000,
  "steps":1000,
  "duration":0,
  "elevation":0,
  }]
},
"results":1

Add Fitness Activity (POST)

Adds a fitness activity record against an individual

Url: https://yourdomain.com/api/fundraiser_activities//{EventID}

Curl example

curl -H "Authentication: bearer MYAPIKEY" -d "data[name]=Morning Run&data[type]=Run&data[date]=2021-04-01&data[distance]=10000"  "https://domain.com/api/fundraiser_activities/1234-5678-9876-6543/123"

POST Data

data=array(
  "name"=>"Name of Activity",
  "type"=>"Type of Activity e.g. Run",
  "duration"=>Duration in seconds,
  "distance"=>Distance in metres,
  "steps"=>1000,
  "date"=>"YYY-MM-DD"
)

Returns

{"success":1,"ID":1234"}

Update Fitness Activity (POST)

Updates a specific fitness activity record against an individual

Url: https://yourdomain.com/api/fundraiser_activities//{EventID}

Curl example

curl -H "Authentication: bearer MYAPIKEY" -d "data[id]=1234&data[name]=Morning Run&data[type]=Run&data[date]=2021-04-01&data[distance]=10000"  "https://domain.com/api/fundraiser_activities/1234-5678-9876-6543/123"

POST Data

data=array(
  "id"=>ID of activity to update,
  "name"=>"Name of Activity",
  "type"=>"Type of Activity e.g. Run",
  "duration"=>Duration in seconds,
  "distance"=>Distance in metres,
  "steps"=>1000,
  "date"=>"YYY-MM-DD"
)

Returns

{"success":1,"ID":1234"}

Delete Fitness Activity (DELETE)

Removes a specific fitness activity record against an individual

Url: https://yourdomain.com/api/fundraiser_activities//{EventID}

Curl example

curl -X DELETE -H "Authentication: bearer MYAPIKEY" -d "data[id]=1234&data[name]=Morning Run&data[type]=Run&data[date]=2021-04-01&data[distance]=10000"  "https://domain.com/api/fundraiser_activities/1234-5678-9876-6543/123"

POST Data

data=array(
  "id"=>ID of activity to update
)

Returns

{"success":1}

Register a Participant (POST)

Creates a new participant record and registers them against an event

Url: https://yourdomain.com/api/fundraiser_register/{EventID}

Curl example

curl -H "Authentication: bearer MYAPIKEY" -d "data[external_id]=1234&data[first_name]=Jim&data[last_name]=Henson&data[email]=jim@henson.com"  "https://domain.com/api/fundraiser_register/123"

POST Data

data=array(
  "external_id"=>Your own ID,
  "first_name"=>"Jim",
  "last_name"=>"henson",
  "email"=>"jim@henson.com",
  "mobile"=>"0404-123-456",
  "send_email"=>true,
)

Returns

{"success":1,"ID":1234"}