Create fundraiser page

Create fundraiser page

This API creates a basic fundraising page for a fundraising account in the VMG system that can be modified by the fundraiser at any time on the main VMG website.

If the person you are creating a page for doesn't already have a VMG fundraising account, you can create one by using the create fundraiser account API.

Pages can be created for a fundraising event that already exists in the VMG system (e.g. the Virgin Money London Marathon) or for any fundraising activity a fundraiser has decided to take part in. To create a page for a VMG event you will need an event resource ID. This can be found in the VMG charity portal, via the event search API, or requested from the VMG helpdesk.

If you're creating a page that isn't for an event, you'll need to pick one of our fundraising activity codes from our activity lookup API.

A page can be created for an individual person or for a group of people raising money as a team. There's a parameter [teampage] that specifies whether you're creating a team or individual page. The page can fundraise for a single charity (that takes 100% of the donations made to the page) or for a number of charities (up to 5, with the same or different percentage splits of the donation). If you're creating a page for an event that is already set up in the VMG system, please note it may be restricted to specific charities and possibly charity splits.

Once a page has been created via the API, an email will be sent to the owner of the fundraising account confirming its creation and supplying a link to it on the VMG site.

URI

Operation type: POST

fundraiserResourceId:

This is the unique resource ID for the fundraising account the page will be created for. It is required, as a page has to be set up against a fundraising account.

If the fundraiser has been asked to authenticate, the successful response contains the ID for the credentials that were used to sign in.

This API is for a protected resource so you will need an access token to create a page. Click here for more info on authentication.

If you have just created a fundraising account, the response will contain the fundraiser's resource ID and an access token. Both are required to create a fundraising page. The token is valid for 1 hour, after which it expires. If it expires, you need to request a new access token via authentication.

Parameter Required Data type Description
pageTitle True Varchar(45)

This is the name of the page which will appear at the top of the fundraising page when viewed on the VMG site.

It is used to identify the page from other pages the fundraiser may have.

The page name is returned by the VMG website when searching for a page.

This can be changed by the fundraiser once the page has been created from within the VMG system.

eventResourceId True/False Varchar(36)

If the page is being created for an event in the VMG system you need to supply its unique identifier, the resource ID.

If you wish the fundraiser to choose from the available events you will need to use the event search API.

An event resource ID can be found in the charity portal under APIs or provided by the VMG helpdesk. They are also returned by the event search API.

Only certain events can be used to set up a page:

  1. The event must have a status of published in VMG. It must not have expired or be in the process of being created.

  2. The event must not require a fee to be collected by Virgin Money Giving as part of the page set up. You can do this using our site, but not via an API call.

  3. If the event has a restricted number of places there must be sufficient places left.

Fundraising for some events is restricted to specific charities and possibly restricted to specific charity split percentages. If you chose an event with restrictions, the charityResourceId and the charitySplitPercentage values must reflect this.

If you are unsure what restrictions are in place you can check in the charity portal if you have access or use the event search API as this returns any restrictions.

fundraisingDate True/False datetime

This is only required if the page is being created for a personal challenge. This parameter is not required for pages for organised events such as the Virgin Money London Marathon.

This is the date on which the fundraising activity is taking place. It appears on the fundraising page and is used by the charities in their management information reports.

The format is YYYYMMDD e.g. if a personal challenge was taking place on 7 January 2014 the entry would be "20140107".

This date can be changed from within the VMG site once it has been created.

teamPageIndicator True Varchar(1)

This indicates if the page is for an individual fundraiser (value 'N') or for a fundraising team (value 'Y'). Team pages allow the page owner to add other fundraisers to the page via the main VMG site.

If the page is being set up as a team then the fundraiser resource ID passed to the API is assumed to be the team owner. Once the team page has been created this fundraiser will need to access the VMG site and add or remove team members.

teamName True/False Varchar(60)

This is only required if the teamPageIndicator passed is a 'Y'.

This is the name of the team. It is returned in the fundraiser search and appears on the fundraising page.

teamUrl True/False Varchar(100)

This is only required if the teamPageIndicator passed is a 'Y'.

This is used to uniquely identify the page in the VMG website, e.g. http://uk.virginmoneygiving.com/team/xxxxxx. The teamURL must be unique and this can be checked using the validate URL API

This allows all team members to promote the same page address when fundraising. The team's URL can be changed from within the VMG site if needed.

activityCode True/False Varchar(3)

This is required if the page is NOT being created for an organised event. If the page is for an event such as the Virgin Money London Marathon this must be left blank.

The code relates to a fundraising activity such as cycling, walking etc. The activity description appears when the page is viewed and the coding is used by the charities in their reporting.

Activity codes can be found by either using the activity lookup API or using IO Docs.

If none of the descriptions match the activity the fundraiser is taking part in, set this to 039 (other) and then enter a description in activityDescription.

activityDescription True/False Varchar(30)

This is required if the page is NOT being created for a VMG event and you have set the activity code to 039 (other).

This is a free format field that allows the entry of an activity description if it doesn't match any of the pre-defined activities. The activtyCode must be set to 039 for this field to contain an entry.

This cannot be changed once the page as been created.

charityContributionIndicator True Varchar(1)

This flag is to let us know if the charity contributed to the cost of the event. Answer 'Y' if the charity has contributed to the cost of accommodation or travel, 'N' if they have not.

If set to a 'Y' an additional question is asked regarding Gift Aid during the donation journey as some scenarios do not allow Gift Aid to be applied.

This cannot be changed once the page has been created.

postEventFundraisingInterval True Int(11)

How long in months fundraising should continue after the event or fundraising date. Set this to 3 if you are unsure as this is the VMG default. The maximum is 36 months.

When this period has passed the system will close the page to new donations and remove it from the VMG search index. A fundraiser signed in to the VMG website is able to reopen the page to donations once it has been closed.

fundraisingTarget False Decimal(19,2)

This is the amount the fundraiser is aiming to raise.

It's not required, but if entered will appear on the fundraising page.

Fundraising pages with a target tend to raise more money than those without.

charityResourceId True Varchar(36)

This is the unique identifier for a charity/charities that the page is fundraising for. Up to 5 charities can be passed.

We need this parameter so we can link the page to the charity/charities.

You can find the charity resource ID in your charity portal, from the VMG helpdesk or if you want a fundraiser to select a charity use the charity search API.

For each charity resource ID there must be a corresponding charitySplitPercent.

If the page is for an event that is restricted to specific charities then these must be used.

charitySplitPercent True Int(11)

A page can be created that is fundraising for up to 5 charities. For each charity you must specify (in whole numbers, no decimals) what percentage they will receive from each donation.

So for a page fundraising for one charity this must be 100. For a page fundraising for two charities, where one will receive 25% and the other 75%, two split percentages are required, 25 and 75.

There must be the same number of splits as there are charities. The first charity split will be applied to the first charity listed, the second split to the second charity and so on.

If the page is for an event that is restricted to specific split percents then these must be used.

Charity split examples

To pass a single charity receiving 100%:

JSON:

"charitySplits":[{"charityResourceId":"05328d10-8d5f-11e2-ad62-005056a8589d",
                             "charitySplitPercent":100}]

To pass multiple charities receiving a share of donations:

JSON:

"charitySplits":[{"charityResourceId":"05328d10-8d5f-11e2-ad62-005056a8589d",
                             "charitySplitPercent":25},

                           {"charityResourceId":"05343034-8d5f-11e2-ad62-005056a8589d",
                             "charitySplitPercent":25},

                           {"charityResourceId":"0527538-4c3e-12a7-bv52-005056a8589d",
                             "charitySplitPercent":50}]

Charity custom codes

The following fields are for charity reporting custom codes for fundraising pages.

They must only be populated if specified by a charity. The data entered here is transformed into our reporting database for use when importing MI into other systems. Up to 5 codes can be specified for each charity.

Parameter Required Data type Description
customCodes False Varchar(255) Do not use unless instructed to by the charity the page is for.

Charity custom codes example

  "charitySplits":[{"charityResourceId":"05328d10-8d5f-11e2-ad62-005056a8589d",
                             "charitySplitPercent":25, 
                             "customCodes":["Page1CC1", "Page1CC2","Page1CC3"]},

                           {"charityResourceId":"05343034-8d5f-11e2-ad62-005056a8589d",
                             "charitySplitPercent":75, 
                             "customCodes":["Page2CC1", "Page2CC2", "Page2CC3", "Page2CC4"]}]

Response

OutcomeFurther information
Success

Page created successfully:

  • Status 201:

Example:

<page>
  <creationSuccessful>true</creationSuccessful>
  <pageTitle>John Smiths Page</pageTitle>
  <pageUrl>1</pageUrl>
  <pageURI>https://sandbox.api.virginmoneygiving.com/fundraisers/v1/account/a38ab8cc-207e-4f89-90b6-2b6a3bc86a7f/pages/1</pageURI>
  <message>Page created successfully</message>
</page>

If your website will include details about your fundraisers with links to their VMG fundraising pages, you have two options regarding the URL to use:

Option 1
You can use their ‘personal URL’. This is the short url assigned to their account as part of the ‘Create Fundraiser Account’ API. It can also be obtained using the Account exists API or the Fundraiser details API. In the vast majority of cases the personal URL will redirect straight to the page you are interested in as most VMG fundraisers only have one active page at a time.

Option 2
A person might have more than one fundraising page open to donations at the same time –for example if they are running the Virgin Money London Marathon and the Bath Half. In which case their personal URL redirects to a landing page that shows all of their active pages, with a click through to each page.

If you want to guarantee that your website links to the correct fundraising page you need to use the full URL of the specific page rather than the personal URL of the fundraiser.

The easiest way to obtain the full URL is to take the pageURI from the response above and, switching to your ‘fundraiser’ package key, use the Fundraising page details API.

Error

Sample error:

If no page details are passed then the following is returned:

  • Error code: 003.01.04
  • Error message: No page details supplied.

Click here for a full list of API error codes.

Error messages

Error codeParameterMessage
003.01.01 teamName Fundraiser team name must be provided for a team page.
003.01.02 teamName Fundraising team name exceeds maximum length.
003.01.03 teamUrl Fundraising team URL exceeds maximum length.
003.01.04 URI No page details supplied. This message occurs when an incorrect URI is passed.
003.01.05 pageTitle A valid page title up to 45 characters is required.
003.01.06 fundraisingDate A fundraising date is not expected for an organised event.
003.01.07 fundraisingDate Please provide a valid fundraising date.
003.01.08 fundraisingDate Please provide a valid fundraising date in the future.
003.01.09 teamPageIndicator Please enter 'Y' or 'N' to indicate if this is a team page.
003.01.10 teamName Please provide a valid team name of up to 60 characters.
003.01.11 teamUrl Please provide a valid team URL of up to 100 characters.
003.01.12 charityResourceId Please provide at least one charity for this fundraising page.
003.01.13 charityResourceId The maximum number of charities allowed (5) has been exceeded.
003.01.14 charityResourceId Charity reference missing for split percent. You have a charity split percentage with no corresponding charityResourceId.
003.01.15 charitySplitPercent The fundraising split does not equal 100 percent. The total of all your charity split percentages must equal 100.
003.01.16 postEventFundraisingInterval Post event open period is invalid. You have entered an incorrect value, e.g. exceeded 36 months or used some letters instead of numbers.
003.01.17 charityContributionIndicator Please tell us if a charity has contributed to your page. This attribute requires either a 'Y' or an 'N'.
003.01.18 activityCode Please provide a valid activity code. Select a valid activity code from the activity lookup API.
003.01.19 activityDescription A description is required for activity type 039 (other). You must enter a description of the activity.
003.01.20 charityResourceId Selected charities do not match event charities. You are setting a page up for an event which is restricted to specific charities. One or more of the charities you have passed is not allowed.
002.01.24 eventResourceId Event not published. The event resource ID is for an event that has not been set up yet.
002.01.25 eventResourceId Event has expired. The event resource ID is for an event that has been removed from the VMG system.
002.01.26 charityResourceId Maximum number of charities has been reached.
002.01.27 eventResourceId Event is fee-based. The event resource ID is for an event that requires a fee to be paid. Please select a different event.
002.01.28 eventResourceId Event limit has been reached. The event resource ID is for an event with a restricted number of places. There are no places left to allocate. Please select a different event.
002.01.29 eventResourceId Event closed. You have provided an event resource ID for an event that has been closed.
002.01.30 charitySplitPercent Event charity split mismatch. You either have a charity split with no percentage or a percentage with no charity.

JSON request example

{"pageTitle":"John Smiths Fundraising Page	",
  "eventResourceId":"",
  "fundraisingDate":"20140101",
  "teamPageIndicator":"N",
  "teamName":"",
  "teamUrl":"",
  "activityCode":"029",
  "activityDescription":"",
  "charityContributionIndicator":"N",
  "postEventFundraisingInterval":"3",
  "fundraisingTarget":"1000",
  "charitySplits":[{"charityResourceId":"05328d10-8d5f-11e2-ad62-005056a8589d",
                             "charitySplitPercent":25, 
                             "customCodes":["customcode 1", " customcode 2"," customcode 3"]},

                           {"charityResourceId":"05343034-8d5f-11e2-ad62-005056a8589d",
                             "charitySplitPercent":75, 
                             "customCodes":["our code AA", " our code AB", " our code DW", " our code TY"]}]
                         }

XML request example

Please note that for XML version parameter is charitysplits, while JSON version is charitySplits.

<?xml version="1.0" encoding="ISO-8859-1" ?> 
<fundraiserpage>
  <pageTitle>My XML Test Page 2</pageTitle>
  <eventResourceId>c5858e1b-a2as-1234-a567-89a0b12c3d36</eventResourceId>
  <fundraisingDate></fundraisingDate>
  <teamPageIndicator>N</teamPageIndicator>
  <teamName></teamName>
  <teamUrl></teamUrl>
  <activityCode></activityCode>
  <activityDescription></activityDescription>
  <charitysplits>
      <charityResourceId>215fbc33-ed8c-4511-bf58-fe83605b5aba</charityResourceId>
      <charitySplitPercent> 100 </charitySplitPercent>
        <customCodes>CC1</customCodes>
        <customCodes>CC2</customCodes>
        <customCodes>CC3</customCodes>
  </charitysplits>
  <charityContributionIndicator>N</charityContributionIndicator>
  <postEventFundraisingInterval>3</postEventFundraisingInterval>
  <fundraisingTarget>1000</fundraisingTarget>
</fundraiserpage>