Charity fundraisers V2

Charity fundraisers V2

This API provides a list of fundraisers who are raising money for the charity resource ID passed. By adding the sort parameters given below, this API can be customised, e.g. to return the top 10 fundraisers by donation value.

Changes from V1 to V2

We have made the fundraiser's title and team member title's optional as we have changed our fundraiser journey to not need these. If you have an existing title with us this will still come through.

Fundraiser accounts now have profile images and their pages have cover images, we return these in this API.

Results pages

As it's possible for a large number of fundraisers to be fundraising for a charity, we restrict the amount of data returned by each API. The numRecords parameter determines the maximum number of rows to return on each call. If this is not passed then the system default (20) is used. To help you move through the dataset the response contains navigation links given below.

Result sorting

The sort order and amount of data returned can be controlled by the following parameters:

  • sortOrder - determines the sequence the data is returned in, ascending (A) or descending (D).
  • sortField - determines which field to sort on.
  • numRecords - determines the number of records to return on each page.
  • startRecordNum - is the record number of the first record to return.

The parameter's case must be the same as given above.

So if an event's top 10 fundraisers (or a charity's top 10 for an event) were required, the following parameters should be set:

  • sortOrder=D
  • sortField=totalDonationGA
  • numRecords=10

URL

Operation type: GET

Call with defaults:
https://api.virginmoneygiving.com/charities/v2/account/{charity resource id}/pages.json?api_key={your API key}

Call to provide top 10 fundraisers for a charity:
https://api.virginmoneygiving.com/charities/v2/account/{charity resource id}/pages.json?sortOrder=D&sortField=donationTotalGA&numRecords=10&api_key={your API key}

Parameter Required Data type Description
charityResourceId True Varchar(36) This is the reference that uniquely identifies the charity.
sortOrder False Varchar(1) This is the sort order of the response. Allowable values are:
A for ascending
D for descending (the default).
sortField False Varchar(30)

This is the field on which to sort. Allowable entries:

donationTotalNet
donationTotalGA (the default)
donationTotalGross
totalGiftAid
offlineAmount

numRecords False Int(3) This is the number of entries to return for a call of the API. The default is 20 records, the maximum is 100.
startRecordNum False Bigint(20) This is the first record number used when paging through the data.
api_key True Varchar (24) This is your key that allows you access to the VMG APIs.

Response

OutcomeFurther information
Success
  • Status 200: OK

Page details, in the following format:

  • Fundraiser's title (optional)
  • Fundraiser's first name
  • Fundraiser's surname
  • Fundraiser resource ID i.e. /fundraisers/v2/account/{fundraiser resource id}
  • Fundraiser's URL
  • Page name
  • Page URL i.e http://uk.virginmoneygiving.com/fundraiser-display/showROFundraiserPage?userUrl={fundraiser url}&pageUrl={page number}
  • Page closed indicator
  • Event name
  • Event resource ID
  • Activity description
  • Activity date
  • Team page / name

If the page is for a team, the following repeats for each team member:

  • Member title (optional)
  • Member first name
  • Member surname
  • Member URI

Page details continued:

  • URL to small fundraiser profile image
  • URL to medium fundraiser profile image
  • URL to large fundraiser profile image
  • URL to small fundraiser cover image
  • URL to medium fundraiser cover image
  • URL to large fundraiser cover image
  • Donation total (net)
  • Gift Aid amount
  • Donation total (inc. Gift Aid)
  • Offline amount
  • Total raised (inc. Gift Aid and offline amount)
  • Number of donations
  • Target amount
  • Offline amount

Charity details:

  • Charity name(s)
Error

Sample error:

If no pages are found for a given charity then the following is returned:

  • Error code: 001.01.005
  • Error message: No fundraiser pages found for charity ref {resource ID}

Click here for a full list of API error codes.

Response description

ParameterData typeDescription
fundraiserName Varchar(122) This is the title, first and last name of the fundraiser.
title Varchar(20) This is the title of the fundraiser – Mr, Mrs etc. (optional)
forename Varchar(50) The first name of the fundraiser.
surname Varchar(50) The last name of the fundraiser.
resourceId Varchar(36) This is the resource ID of the fundraiser.
personalUrl Varchar(45) This is the URL for the fundraiser's VMG account which will show any fundraising pages they have.
fundraiserURI Varchar(100) This is the API link to the fundraiser in the VMG system. For use with the fundraiser details API.
pageName Varchar(45) The name of the page the fundraiser has given it.
pageUrl Varchar(45) The page URL the fundraiser has given it.
pageClosedInd Varchar(1) An indicator 'Y' or 'N' informing whether the page is closed. A closed page cannot collect donations but it can be accessed by the fundraiser who owns the page.
eventName Varchar(255) If the page has been set up for an organised event, e.g. the Virgin Money London Marathon, this is the name of the event on the VMG system.
eventResourceId Varchar(255) If the page is for an event this is the event's resource ID.
activityDescription Varchar(255) This is the description of the fundraising activity.
activityDate Datetime This is the date the fundraising event or activity is taking place.
teamPage Varchar(10) This is set to ‘true’ for team pages and ‘false’ for individual pages.
teamName Varchar(45) The name of the fundraising team.
teamMembers Varchar(1024) The names of the fundraisers in the team.
profileImageSmall Varchar(100) This is the link to the small fundraiser profile image.
profileImageMedium Varchar(100) This is the link to the medium fundraiser profile image.
profileImageLarge Varchar(100) This is the link to the large fundraiser profile image.
coverImageSmall Varchar(100) This is the link to the small fundraiser cover image.
coverImageMedium Varchar(100) This is the link to the medium fundraiser cover image.
coverImageLarge Varchar(100) This is the link to the large fundraiser cover image.
donationTotalNet Decimal(19,2) This is the donation total for the page, excluding Gift Aid and any offline donation amount.
totalGiftAid Decimal(19,2) This is the Gift Aid amount applied to the page.
donationTotalGa Decimal(19,2) This is the donation total including Gift Aid and excluding any offline donation amount.
offlineAmt Decimal(19,2) This is the total amount of donations that have not gone through the fundraising page but have been collected elsewhere.
donationTotalGross Decimal(19,2) This is the donation total for the page, including Gift Aid and any offline donation amount.
numberOfDonations Int(10) This is a count of the donations that have been applied to the page.
targetAmount Decimal(19,2) This is the amount the fundraiser is hoping to raise.
Charity details – the following repeats for each charity:
name Varchar(150) This is the name of the charity the page is fundraising for.

Navigation links

The response also contains navigation links.

To prevent excessive load on our servers this API returns pages of data rather than the complete data set. To help you retrieve data this API returns the following navigation links:

ParameterDescription
rel="first" This is the link to the first page of data.
rel="prev" This is the link to the last page of data that was returned.
rel="next" This is the link to the next page of data.
rel="last" This is the link to the last page of data.

Example links:

http://api.virginmoneygiving.com/charities/v2/account/6ec5ad6c-b702-11e2-aba0-00237d9ded4e/pages?startRecordNum=1&numRecords=20>;rel="first"

http://api.virginmoneygiving.com/charities/v2/account/6ec5ad6c-b702-11e2-aba0-00237d9ded4e/pages?startRecordNum=1&numRecords=20>; rel="prev"

http://api.virginmoneygiving.com/charities/v2/account/6ec5ad6c-b702-11e2-aba0-00237d9ded4e/pages?startRecordNum=22&numRecords=20>; rel="next"

http://api.virginmoneygiving.com/charities/v2/account/6ec5ad6c-b702-11e2-aba0-00237d9ded4e/pages?startRecordNum=-1&numRecords=20>; rel="last"

XML response example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<fundraiserDetailsV2>
    <fundraiserDetail>
        <fundraiserName>Mr John Smith</fundraiserName>
        <title>Mr</title>
        <forename>John</forename>
        <surname>Smith</surname>
        <resourceId>6461f218-b702-11e2-aba0-00237d9ded4e</resourceId>
        <personalUrl>http://uk.virginmoneygiving.com/JohnSmith</personalUrl>
        <fundraiserURI>https://api.virginmoneygiving.com/fundraisers/v2/account/6461f218-b702-11e2-aba0-00237d9ded4e</fundraiserURI>
        <pageDetails>
            <page>
                <pageName>John Smith's fundraising page</pageName>
                <pageUrl>http://uk.virginmoneygiving.com/fundraiser-display/showROFundraiserPage?userUrl=JohnSmith&pageUrl=2</pageUrl>
                <pageClosedIndicator>N</pageClosedIndicator>
                <eventName>Test Event</eventName>
                <eventResourceId>6ec58742-b702-11e2-aba0-00237d9ded4e</eventResourceId>
                <activityDate>20130728</activityDate>
                <teamPage>false</teamPage>
                <teamPage>false</teamPage>
                <teamMembers/>
                <donationTotalNet>0.00</donationTotalNet>
                <totalGiftAid>0.00</totalGiftAid>
                <donationTotalGA>0.00</donationTotalGA>
                <offlineAmount>0.00</offlineAmount>
                <donationTotalGross>0.00</donationTotalGross>
                <numberOfDonations>0</numberOfDonations>
                <targetAmount>0.00</targetAmount>
                <charityDetails>
                    <charity>
                        <name>Test Charity</name>
                    </charity>
                </charityDetails>
            </page>
        </pageDetails>
    </fundraiserDetail>
</fundraiserDetailsV2>

JSON response example

{
    "fundraiserDetailsV2": [{
        "fundraiserName": "Mr John Smith",
        "title": "Mr",
        "forename": "John",
        "surname": "Smith",
        "resourceId": "633969d4-b702-11e2-aba0-00237d9ded4e",
        "personalUrl": "http://uk.virginmoneygiving.com/JohnSmith",
        "fundraiserURI": "https://api.virginmoneygiving.com/fundraisers/v2/account/633969d4-b702-11e2-aba0-00237d9ded4e",
        "pageDetails": [{
            "pageName": "John Smith's Fundraising page",
            "pageUrl": "http://uk.virginmoneygiving.com/fundraiser-display/showROFundraiserPage?userUrl=JohnSmith&pageUrl=2",
            "pageClosedIndicator": "N",
            "eventName": "Test Event",
            "eventResourceId": "6ec58742-b702-11e2-aba0-00237d9ded4e",
            "activityDescription": null,
            "activityDate": "20130728",
            "teamPage": false,
            "teamName": null,
            "teamMembers": [],
            "profileImageSmall": "http://uk.virginmoneygiving.com/resources/fundraiser-images/74x926397a698-b702-11e2-aba0-00237d9ded4e.jpg",
            "profileImageMedium": "http://uk.virginmoneygiving.com/resources/fundraiser-images/100x1006397a698-b702-11e2-aba0-00237d9ded4e.jpg",
            "profileImageLarge": "http://uk.virginmoneygiving.com/resources/fundraiser-images/167x1876397a698-b702-11e2-aba0-00237d9ded4e.jpg",
            "coverImageSmall": "http://uk.virginmoneygiving.com/resources/fundraiser-images/960x6006397a698-b702-11e2-aba0-00237d9ded4e.jpg",
            "coverImageMedium": "http://uk.virginmoneygiving.com/resources/fundraiser-images/960x6006397a698-b702-11e2-aba0-00237d9ded4e.jpg",
            "coverImageLarge": "http://uk.virginmoneygiving.com/resources/fundraiser-images/2080x9006397a698-b702-11e2-aba0-00237d9ded4e.jpg",
            "donationTotalNet": 0.00,
            "totalGiftAid": 0.00,
            "donationTotalGA": 0.00,
            "offlineAmount": 0.00,
            "donationTotalGross": 0.00,
            "numberOfDonations": 0,
            "targetAmount": 0.00,
            "charityDetails": [{
                "name": "Test Charity"
            }]
        }]
    }]
}