Event search

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 search

This API can be used to allow a fundraiser, when creating a page, to select an organised fundraising event to join.

This API returns the information about events that match the search criteria. This API takes one or two parameters – a partial event name and/or a date (year and month only). Only open events that are still possible to join are returned.

Some organised events raise money for specific charities so it's not always possible to nominate a recipient charity.

Where an event contains a restricted number of charities, these charities are returned by the API. If they are returned they must be used, with any split percent if present, when creating a page for that event.

URL

Operation type: GET

https://api.virginmoneygiving.com/events/v1/search.json?name={event name}&date={yyyymm}&api_key={your API key}

At least one parameter, partial name or date must be passed to the API.

Parameter Required Data type Description
name False Varchar(50) Partial or full event name.
date False Varchar(6) This is the year and month to search in.
api_key True Varchar(24) This is your key that allows you access to the VMG APIs.

Response

OutcomeFurther information
Success

If the search criteria match one or more events the following is returned:

  • Status 200: OK

List of matching events, in the following format:

  • Name
  • Event description
  • Event date
  • Event location
  • Charities (If the event is restricted)
  • Charity name
  • Charity resource ID
  • Charity split
  • Event summary URI i.e. /v1/events/{event resource id}/summary
  • Event resource ID
Error

Sample error:

If no event matches the search criteria 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

Data itemData typeDescription
name Varchar(122) This is the full name of the event.
eventDescription Varchar(1024) This is a description of the event.
eventURI Varchar(100) This is the URI to access the event.
eventResourceId Varchar(36) This is the unique identifier for the event.
eventLocation Varchar(255) Where the event is taking place – county.
eventDate Datetime The date on which the event is taking place.
The following three fields repeat if the event is restricted to specific charities.
charityResourceId Varchar(36) This is the identifier that uniquely identifies the charity.
charityName Varchar(150) This is the full name of the charity.
charitySplitPercent Int(10)

This is the percentage amount of fundraising the charity will receive. If this contains a value then when creating a fundraising page for the event this value must be passed in the API.

If this returns '0' then there is no restriction for the amount the charity can receive.

 

XML response example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<events>
    <event>
        <name>Test Event</name>
        <eventDescription>Annual 10K Run</eventDescription>
        <eventURI>https://api.virginmoneygiving.com/events/v1/account/6ec58742-b702-11e2-aba0-00237d9ded4e/summary</eventURI>
        <eventResourceId>6ec58742-b702-11e2-aba0-00237d9ded4e</eventResourceId>
        <eventLocation>International</eventLocation>
        <eventDate>20130728</eventDate>
        <charities>
            <charity>
                <charityResourceId>703af0e4-b702-11e2-aba0-00237d9ded4e</charityResourceId>
                <charityName>Test Charity</charityName>
                <charitySplitPercent>100</charitySplitPercent>
            </charity>
        </charities>
    </event>
</events>

JSON response example

{
    "message": null,
    "events": [{
        "name": "Test Event",
        "eventDescription": "Annual 10K Run",
        "eventURI": "https://api.virginmoneygiving.com/events/v1/account/6ec58742-b702-11e2-aba0-00237d9ded4e/summary",
        "eventResourceId": "6ec58742-b702-11e2-aba0-00237d9ded4e",
        "eventLocation": "International",
        "eventDate": "20130728",
        "charities": {
            "charity": [{
                "charityResourceId": "703af0e4-b702-11e2-aba0-00237d9ded4e",
                "charityName": "Test Charity",
                "charitySplitPercent": "100"
            }]
        }
    }]
}

version 35 as of 2 years ago by marc