Event fundraisers 2 V2

Virgin Money Giving has closed

Page and account creation APIs are now unavailable so please consider your use of our APIs and how this affects you. All other APIs will be available until 18 February. If you have any questions please take a look at our Q&A.

Read our Q&A

Event fundraisers 2 V2

This API is only available to Event Package users and is an enhanced version of the ‘Event fundraisers’ API.

In addition to providing a list of fundraisers who have set up a fundraising page for the event resource ID passed, this enhanced version also provides details of the charity categorisation(s) e.g. Mental Health.

This page focuses on the additional content offered, and should be used in conjunction with the Event fundraisers API for details of sort parameters available & navigation links.

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.

URI

Operation type: GET

https://api.virginmoneygiving.com/events/v2/account/{event resource id}/categorisedpages.json?api_key={your API key}

Parameter Required Data type Description
eventResourceId True Varchar(36) This is the reference that uniquely identifies the event.
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

Outcome Further 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}
  • 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:

  • Profile images
  • Cover images
  • 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)

For each charity, details are given of their categorisation(s).

Charity categorisation:

  • Category title (e.g. Culture)
  • Category subtitle (e.g. Art)
Error

Sample error:

If no matching event details are found then the following is returned:

  • Error code: 004.01.04
  • Error message: No matching events found for your search criteria

Click here for a full list of API error codes.

Response description

Parameter Data type Description
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.
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 name of the page the fundraiser has given it.
pageClosedInd Varchar(1) An indicator 'Y' or 'N' informing whether the page is closed. A closed page can not 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.
offlineAmount 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 repeat for each charity:
Name Varchar(150) This is the name of the charity the page is fundraising for.
Charity categorisation details, the following repeat for each category per charity:
categoryTitle Varchar(50) This is the high level category e.g. Health
categorySubTitle Varchar(50) This is the lower level categorisation e.g. Cancer

XML response example (extract)

The response is virtually identical to the example in the event fundraisers documentation, the only difference (extract shown below) is the inclusion of the new category fields within the charity details section.

<charityDetails>
    <charity>
        <name>Test Charity A</name>
        <charityCategories>
            <charityCategory>
                <categoryTitle>Culture</categoryTitle>
                <categorySubTitle>Art</categorySubTitle>
                    </charityCategory>
                        </charityCategories>
    </charity> 
</charityDetails>

JSON response example (extract)

Refer to the Event Fundraisers documentation for the full response, the example below focuses on the additional content returned by this API re charity categories.

{
    "emailAddress": "example@example.com",
    "dayOfBirth": 3,
    "monthOfBirth": 1,
    "yearOfBirth": 1980,
    "accountExistsIndicator": false,
    "resourceId": null,
    "createPageIndicator": false,
    "accountURL": null
}

version 4 as of 7 months ago by marc