Create fundraiser account

Create fundraiser account

This API creates a fundraiser account. A fundraiser account is required to be able to create a fundraiser page.

The email and date of birth provided in this call are used by the account holder to log into their VMG account. When the account has been created we will send the fundraiser a welcome email (sent to the email address provided in the API) containing a temporary password which is needed to log into VMG. The first time the fundraiser logs into VMG they will be prompted to change their password.

When you create an account, the API response will include a token that allows you to create a page for this account. You’ll need to use this access token before it expires.

You should also provide the redirect_uri for your application. This is configured in the 'Application' tab in the 'My account' page. Select the 'Edit' option and update the the 'Call back URL'.

URL

Operation type: POST

https://api.virginmoneygiving.com/fundraisers/v1/newaccount?redirect_uri=(your call back URL}&api_key={your API key}

Parameter Required Data type Description
title True Varchar(20) The allowable values for this field are: Mr, Mrs, Ms, Miss, Dr, Prof.
forename True Varchar(50) This is the account holder's first name.
surname True Varchar(50) This is the account holder's last name.
addressLine1 True Varchar(50) First line of the account holder's address.
addressLine2 True Varchar(100) Second line of the account holder's address.
townCity True Varchar(100) Account holder's town or city.
countyState True Varchar(100) Account holder's county.
postcode True/False Varchar(10)

This is required if the address is in the UK.

If the postcode contains a space this needs to be included.
countryCode True Varchar(10) This is the country code corresponding to the country the address is in. Country codes can be obtained from the country code API.
preferredTelephone True Varchar(20) Fundraiser's telephone number.
emailAddress True Varchar(255)

This is the fundraiser's email address.

Any emails generated by Virgin Money Giving for the fundraiser are sent to this address. e.g. donation notifications.

If the account is successfully created via the API, this email address will receive a confirmation email which also contains a temporary password for the account. This must be changed when the fundraiser first signs into their account.

The email address and date of birth are used along with a password to sign in to Virgin Money Giving.
personalUrl True Varchar(100)

This is used to access and promote the fundraising pages.

The personal URL must be unique and can be checked beforehand by using the validate URL API.

e.g. http://uk.virginmoneygiving.com/{url} Where {url} is the value you enter in this field.

This can be changed from within the portal at any time.
termsAndConditionsAccepted True Varchar(1)

The fundraiser must have been given access to the Virgin Money Giving terms and conditions. This must be set to ‘Y’ once the fundraiser has confirmed they have read the terms and conditions. If the fundraiser has not accepted the terms and conditions the fundraising account cannot be created.

The terms and conditions can be found here.
charityMarketingIndicator True Varchar(1)

This field is no longer used. However it remains mandatory and must be passed as ‘N’ for all users.
allCharityMarketingIndicator True Varchar(1)

This field is no longer used. However it remains mandatory and must be passed as ‘N’ for all users.
virginMarketingIndicator True Varchar(1)

This field is no longer used. However it remains mandatory and must be passed as ‘N’ for all users.
dateOfBirth False Varchar(8)

This is the fundraiser's date of birth, which must be supplied in the following format: YYYYMMDD.
vmgMarketingIndicator True Varchar(1)

This field is no longer used. However it remains mandatory and must be passed as ‘N’ for all users.

If a charity this fundraiser is fundraising for requires custom reporting codes to be set up, the following fields should be used.

They must only be populated if specified by a charity. The data entered here is transformed for use by charities in their reporting systems.

Parameter Required Data type Description
fundraiserCustomCode False Varchar(255)

Do not use unless instructed to by a charity.

Up to five codes can be specified.
charityResourceId False Varchar(36) If the fundraising account requires custom codes to be set, this is the charity's unique reference to which they will be applied. This resource ID can be found within the VMG charity portal or the response for the charity search API.

XML request example

This request creates an account for a UK based address:

<fundraiserAccount>
	<title>Mr</title>
 	<forename>John</forename>
	<surname>Smith</surname>
	<addressLine1>Address line 1</addressLine1>
	<addressLine2>Address line 2</addressLine2>
	<townCity>Norwich</townCity>
	<countyState>Norfolk</countyState>
	<postcode>NR4 6EJ</postcode>
	<countryCode>GB</countryCode>
	<preferredTelephone>01603215715</preferredTelephone>
	<emailAddress>test@virginmoneygiving.com</emailAddress>
	<personalUrl>mytesturl</personalUrl>
	<termsAndConditionsAccepted>Y</termsAndConditionsAccepted>
	<charityMarketingIndicator>N</charityMarketingIndicator>
	<allCharityMarketingIndicator>N</allCharityMarketingIndicator>
	<virginMarketingIndicator>N</virginMarketingIndicator>
	<dateOfBirth>19610118</dateOfBirth>
	<vmgMarketingIndicator>N</vmgMarketingIndicator>
</fundraiserAccount>

JSON request example

This request creates an account for a UK based address:

{"title":"Mr",
  "forename":"John",
  "surname":"Smith",
  "addressLine1":"Address line 1",
  "addressLine2":"Address line 2",
  "townCity":"Norwich",
  "countyState":"Norfolk",
  "postcode":"NR4 6EJ",
  "countryCode":"GB",
  "preferredTelephone":"01603215715",
  "emailAddress":"test@virginmoneygiving.com",
  "personalUrl":"mytesturl",
  "termsAndConditionsAccepted":"Y",
  "charityMarketingIndicator":"N",
  "allCharityMarketingIndicator":"N",
  "virginMarketingIndicator":"N",
  "dateOfBirth":"19610118",
  "vmgMarketingIndicator":"N"
  }

Response

OutcomeFurther information
Success A successful account creation will return the following:
  • Status 200: OK

Fundraiser details, in the following format:

  • Fundraiser resource ID
  • Fundraiser URL
  • Link to fundraiser URI i.e. /v1/fundraisers/{fundraiseruuid}
  • Access token
Error

Sample error:

If no account details are provided then the following is returned:

  • Error code: 002.01.02
  • Error message: Cannot create fundraiser account - no details supplied.

Click here for a full list of API error codes.

Response description

Data item Data type Description
creationSuccessful Varchar(10) Returns true if the fundraiser creation is successful and false if it isn't.
fundraiserName Varchar(122) The title, forname and surname of the fundraiser.
resourceId Varchar(36) This is the resource ID of the fundraiser.
personalUrl Varchar(100) This is the fundraiser personal VMG website URL.
accessToken Varchar(36)

Once you have created a fundraiser account you need to create a page. The URI for the page creation, which is a protected resource, requires an access token or for the fundraiser to sign in to their account.

You need this access token to create a page for the fundraiser, but don't take too long as the token has a limited life.
responseURI Varchar(100) This is the URI to the fundraiser's details.
customerExists Varchar(10) Returns True if the fundraiser already has an account in VMG for the date of birth and email address combination.
message Varchar(100) Notification of the access token life expectancy.

XML response example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<fundraiser>
<creationSuccessful>true</creationSuccessful>
<fundraiserName>Mr John Smith</fundraiserName>
<resourceId>11f5f732-4f23-4518-8312-ce1551339776</resourceId>
<personalUrl>http://uk.sandbox.virginmoneygiving.com/mytesturl</personalUrl>
<accessToken>c88c6d1a-ceff-41cd-9d9c-481b70826c8f</accessToken>
<responseURI>https://sandbox.api.virginmoneygiving.com/fundraisers/v1/account/11f5f732-4f23-4518-8312-ce1551339776</responseURI>
<customerExists>false</customerExists>
<message>Token expires in 600 seconds</message>
</fundraiser>

JSON response example

{
    "creationSuccessful": true,
    "fundraiserName": "Mr John Smith",
    "resourceId": "318fc319-3b19-4314-9c8d-404b14e51eb2",
    "personalUrl": "http://uk.sandbox.virginmoneygiving.com/mytesturl",
    "alternateURLs": null,
    "accessToken": "mdznarvxftjk2p365tyv7zp8",
    "responseURI": "https://sandbox.api.virginmoneygiving.com/fundraisers/v1/account/318fc319-3b19-4314-9c8d-404b14e51eb2",
    "customerExists": false,
    "message": "Token expires in 600 seconds"
}

Error Messages

Error code Parameter Message
002.01.01 No fundraiser details provided.
002.01.02 Cannot create fundraiser account - no details supplied.
002.01.03 countryCode Country code is invalid. Select a valid code from the country code API.
002.01.04 title Title is invalid. The only titles we accept are: Mr, Mrs, Ms, Miss, Dr, Prof.
002.01.05 personalUrl Fundraiser URL not supplied. You need to provide a valid and unique fundraiser URL
002.01.06 surname Surname is invalid. Please provide a value up to 50 characters. The length of the surname has been exceeded.
002.01.07 forename Forename is invalid. Please provide a value up to 50 characters. The length of the forename has been exceeded.
002.01.08 termsAndCondtionsAccepted An account cannot be created if the terms and conditions are not accepted. We can only create an account if the fundraiser has accepted our terms and conditions.
002.01.09 emailAddress Email addresses must be up to 255 characters. The length of the email address exceeds 255.
002.01.10 emailAddress Email addresses format is invalid. The email address must contain an @ symbol and at least 2 full stops.
002.01.11 preferredTelephone Please provide a valid phone number. A phone number is required.
002.01.12 preferredTelephone A valid phone number up to 16 digits must be provided. The phone number exceeds 16 characters or contains entries other then numerics.
002.01.13 dateOfBirth Please provide a date of birth in YYYYMMDD format. The date of birth was not provided.
002.01.14 dateOfBirth Please provide a valid date of birth in YYYYMMDD format. The date of birth provided is not in the correct format.
002.01.15 dateOfBirth Fundraiser age should be between 13 and 100 years. From the date of birth you have provided we have calculated it fails the above validation.
002.01.16 postcode Postcode should not exceed 8 characters. The post code is a required field for UK addresses. Please use our postcode look up for postcode validation or supply the it in the correct format.
002.01.17 postcode The postcode must be in one of the Royal mail prescribed formats. The post code is a required field for UK addresses. Please use our postcode look up for postcode validation or supply the it in the correct format.
002.01.19 addressLine1 / townCity Please provide the first line of addresses and the town or city name. The first line of the address is a required field.
002.01.20 personalUrl Fundraiser URL is invalid. Please provide a value up to 60 characters.
002.01.21 charityResourceId A valid charity resource id must be provided if creating custom codes.
002.01.22 customCodes Please provide up to 5 valid custom codes
002.01.23 customCodes A maximum of 5 custom codes are allowed.
002.01.31 emailAddress / dateOfBirth A Virgin Money Giving account already exists for the given Email addresses and Date of birth.

version 56 as of 1 year ago by marchumphries