Event summary

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 summary

This returns the total summarised donations, the number of fundraisers there are, and the number of fundraising pages that have been created for an event.

This API can be called in one of two ways:

If you have access to the charity package, the API must be called with an event resource ID and a charity resource ID which totals all of the charity's donations, pages and fundraisers for an event.

OR

If you have access to the event package you must call this API with just an event reference which totals all of the donations, pages and fundraisers for an event.

Donations made to pages should appear in the summary a few minutes after being made.

URL

Operation type: GET

This is the URI to total a charity's donations for a charity package:

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

This is the URI to total all of the donations for an event package:

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

Parameter Required Data type Description
eventResourceId True Varchar(36) This is the unique reference for the event.
charityResourceId True Varchar(36) This is the unique reference for the charity and only required if you have a charity package.
api_key True Varchar (24) This is your key that allows you access to the VMG APIs.

Response

OutcomeFurther information
Success

If the event resource ID (and charity resource ID if passed) matches an entry in the database then the following is returned:

  • Status 200: OK

Event details, in the following format:

  • Event name
  • Event resource ID
  • Charity resource ID (if passed)
  • Charity name
  • Number of fundraisers
  • Number of fundraising pages
  • Donation total (net)
  • Gift Aid amount
  • Donation total (inc. Gift Aid)
  • Offline amount
  • Total raised (inc. Gift Aid and offline amount)
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

How the totals are calculated is dependant on the parameters passed.

Event only – the totals are for the event.
Event/Charity - the totals for the event are restricted to the charity.

Data itemData typeDescription
eventName Varchar(255) This is the name of the event.
eventResourceId Bigint(10) This is the unique reference for the event.
fundraiserCount Integer(10) This is a count of the total number of fundraisers fundraising for the event.
fundraiserPageCount Integer(10) This is the number of fundraising pages that are linked to the event.
donationTotalNet Decimal(19,2) This is the donation total excluding Gift Aid and any offline fundraising.
giftAidAmount Decimal(19,2) This is the total Gift Aid donated to the event.
donationTotalGA Decimal(19,2) This is the donation total including Gift Aid and excluding any offline fundraising.
offLineAmount Decimal(19,2) This is the total of any offline amounts raised for the event. This is the 'Offline fundraising' as seen on a fundraiser's page.
donationTotalGross Decimal(19,2) This is the donation total including Gift Aid and any offline fundraising amount applied to the page.

XML response example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<eventSummary>
    <eventName>Test Event</eventName>
    <eventResourceId>6ecf0592-b702-11e2-aba0-00237d9ded4e</eventResourceId>
    <charityResourceId>70027b06-b702-11e2-aba0-00237d9ded4e</charityResourceId>
    <charityName>Test Charity</charityName>
    <fundraiserCount>25</fundraiserCount>
    <fundraiserPageCount>25</fundraiserPageCount>
    <donationTotalNet>14708.00</donationTotalNet>
    <giftAidAmount>367.70</giftAidAmount>
    <donationTotalGA>15075.70</donationTotalGA>
    <offLineAmount>20.00</offLineAmount>
    <donationTotalGross>15095.70</donationTotalGross>
</eventSummary>

JSON response example

{
    "eventName": "Test Event",
    "eventResourceId": "6ecf0592-b702-11e2-aba0-00237d9ded4e",
    "charityResourceId": "70027b06-b702-11e2-aba0-00237d9ded4e",
    "charityName": "Test Charity",
    "fundraiserCount": 25,
    "fundraiserPageCount": 25,
    "donationTotalNet": 14708.00,
    "giftAidAmount": 367.70,
    "donationTotalGA": 15075.70,
    "offLineAmount": 20.00,
    "donationTotalGross": 15095.70
}

version 37 as of 1 year ago by marc