- Previous: Account Exists
- Up: Introduction
- Next: Activity lookup
Create fundraiser account
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.
Documentation
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
Outcome | Further information |
---|---|
Success | A successful account creation will return the following:
Fundraiser details, in the following format:
|
Error |
Sample error: If no account details are provided then the following is returned:
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. |
- Previous: Account Exists
- Up: Introduction
- Next: Activity lookup
Docs Navigation
- Introduction
- Getting started
- Fundraiser search
- Fundraiser details
- Fundraiser details V2
- Fundraising page details
- Fundraising page details V2
- Charity search
- Validate URL
- Country code lookup
- Address lookup
- Account Exists
- Create fundraiser account
- Activity lookup
- Event search
- Create fundraiser page
- Event summary
- Event fundraisers
- Event Fundraisers V2
- Event fundraisers 2
- Event fundraisers 2 V2
- Charity fundraisers
- Charity fundraisers V2
- Charity details
- Authentication
- Useful information
- Error codes
- Glossary
- Software development kit