Account Exists

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

Account exists

This API allows a Charity or Event Organiser to identify whether an individual already has an account on VMG by matching on email address and date of birth. The response also informs whether it is possible to create a fundraising page for them using our APIs.

It is not possible to create a fundraising page using our APIs if an existing account does not already have a URL associated with it (e.g. they are a charity user, or a registered donor only). The individual should instead be instructed to sign into the main VMG site and create their page manually.

Flow chart Account Exists process

URI

Operation type: GET

https://api.virginmoneygiving.com/fundraisers/v1/validateaccount.json?api_key={your API key}&emailAddress={email address}&dateOfBirth={date of birth}

Parameter Required Data type Description
api_key True Varchar(24) This is your key that allows you access to the VMG APIs.
emailAddress True Varchar(255) This is the full email address of the person taking part in your event.
dateOfBirth False Varchar(8) This is the date of birth of the person taking part in your event, in the format YYYYMMDD.

Response

Outcome Further information
Success – match found

Success – match found If a matching record is found in the database then the following is returned:

  • Status 200: OK
  • Email address (emailAddress)
  • Day of birth (dayOfBirth)
  • Month of birth (monthOfBirth)
  • Year of birth (yearOfBirth)
  • Account exists flag (accountExistsIndicator) = true
  • Fundraisers resource ID (resourceId)
  • Flag to indicate whether it will be possible to create a page (createPageIndicator) = true
  • Fundraisers URL (accountUrl)

It is not necessary to create a fundraiser account if the API returns accountExistsIndicator = true.

Next steps:

If the API response informs that it is possible to create a page:

If the API response informs that it is not possible to create a page:

  • If the account exists within the VMG database but it does not already have a fundraiser URL it is not possible to create a page using the API
  • Our recommended approach is to display a message within your screens that informs the user that unfortunately it is not possible to automatically create a fundraising page for them and that they should sign into their account in VMG and create a page manually for this event.

Fundraisers URL:

The fundraisers short URL is included for your convenience as in the majority of cases this will redirect to the page you are creating.

However this carries the caveat that in VMG it possible for an individual to have several active fundraising pages at the same time, in which case the short URL navigates to a landing page where users must then select which of the active pages they wish to view.

The long URL for your specific page can be obtained using either the Charity fundraisers API, the Event fundraisers API or from the response when creating a page.

Success – match not found

If the account does not exist in the VMG database then the following is returned:

  • Status 200: OK
  • Email address (emailAddress)
  • Day of birth (dayOfBirth)
  • Month of birth (monthOfBirth)
  • Year of birth (yearOfBirth)
  • Account exists flag (accountExistsIndicator) = false
  • Is it possible to create a page flag (createPageIndicator)

Error

Sample error:

If API call does not contain all the required search criteria then the following is returned:

  • Error code: 001.02.013
  • Error message: Please provide a valid email address and a date of birth (in YYYYMMDD format)

Click here for a full list of API error codes.

XML response example (account exists)

<accountCheck>
    <emailAddress>example @example.com</emailAddress>
    <dayOfBirth>31</dayOfBirth>
    <monthOfBirth>12</monthOfBirth>
    <yearOfBirth>1970</yearOfBirth>
    <accountExistsIndicator>true</accountExistsIndicator>
    <resourceId>12a3456b-c789-0d12-3456-7e89fg01hi2j</resourceId>
    <createPageIndicator>true</createPageIndicator>
    <accountUrl>
        http://virginmoneygiving.com/JoeBloggs
    </accountUrl>
</accountCheck>

JSON response example (account does not exist)

{
    "emailAddress": "example@example.com",
    "dayOfBirth": 3,
    "monthOfBirth": 1,
    "yearOfBirth": 1980,
    "accountExistsIndicator": false,
    "resourceId": null,
    "createPageIndicator": false,
    "accountURL": null
}

version 8 as of 7 months ago by marc