Frequently Asked Questions
Frequently asked questions
Here are some questions you've asked us about Virgin Money Giving APIs.
You'll also find practical information about using our APIs on the forum.
If you can't find an answer to your question, please contact us.
Getting started with Virgin Money Giving APIs
- What is an API?
An API (Application Programming Interface) provides developers with the means to interact directly with an external platform without needing to visit their website directly.
Virgin Money Giving APIs have been designed to give developers a means to return fundraising information and for charities and event owners the ability to create Virgin Money Giving accounts and pages from within your own site.
- How do I register as a developer?
Simply select the 'Register' option in the top right of the page to create your developer account. You'll be asked to register a new Mashery ID for access to this site. Mashery are our API partner and if you have already registered with them to access another company's APIs, you can use those details to sign in to this site.
To create a new account you'll need to tell us a few things such as who you are, who you work for (if you're developing on behalf of a company) and some contact information. You will also need to choose a username for the account and a display name (which others will see when they view your profile or you leave a comment on the forum). Then choose a password for your account which must contain at least one letter, at least one number and contain at least 8 characters.
When you register your new account, you'll be sent a confirmation email. You will need to click the link in the email to activate your account. Once your account is active you'll be able to request keys and leave comments in the forum.
- What is an API package?
We have grouped our APIs in sets designed to meet the needs of fundraiser, charity or event developers. We refer to these sets as packages.
- Which API package is right for me?
We've packaged together groups of APIs into 3 sets designed to meet the needs of fundraisers, charities and event organisers.
The fundraiser package will let you find fundraisers on Virgin Money Giving and return information from their active fundraising pages - perfect for building widgets, utilising social media and comparing your fundraising with others.
The charity package is perfect for charities to call sumamrised information on the people and events that are raising money for them.
The event package is designed to let event organisers call summarised information on the people taking part and the charities they've chosen to fundraise for.
Both charity and event packages have the ability to create Virgin Money Giving fundraiser accounts and pages via API. This fantastic feature means you can can enrol people who sign up for your events as fundraisers on Virgin Money Giving ready to start receiving donations as soon as they've registered on your site.
- What is an API plan?
When you've chosen your API package and apply for a key, you'll see a subset of information called a plan. Your plan will tell you which environments you can access with your key (sandbox, production or both) and also your API key rate limit. You can find information on the packages and plans you hold at any time by signing in to your developer account.
- What is a resource ID?
Access to information on Virgin Money Giving is via unique identifiers known as resource IDs. Each resource - fundraiser, charity or event has its own unique identifier. You can find your own resource IDs on the VMG website by logging in as a fundraiser or charity administrator.
Since these IDs uniquely identify a resource, please take all reasonable care to keep them confidential and avoid exposing them publicly in your applications or code.
Event organisers may search for charity IDs and charities may search for event IDs using their respective API packages, but one charity cannot search another charity resource ID and the same goes for events.
- How do I get a key for the Virgin Money Giving APIs?
Once you've registered and signed in to your developer account, visit the our APIs page and select the package that's right for you. We have bundled our APIs into three sets designed to meet the needs of fundraisers, charities and event organisers.
When you apply for a key please include as much detail as possible on what you're planning to develop and where it will be used. We moderate requests for multiple keys and requests for production access for charity and event package keys, so including this information will help us do so quickly. If you see your key staus as 'waiting' when you sign in to your account, this means we need to review your application. We do this during business hours (Monday to Friday, 9.00am to 5.30pm).
- What is a key rate limit?
A key rate limit is the number of calls your key is entitled to make to Virgin Money Giving APIs. You can find out what limits apply to your key by signing in to your developer account.
Limits are both per second and per day. You'll be sent an alert to the email address you used to register your application if you are nearing your daily call limit and another if you exceed your per second or per day limit. Please be aware that if you make more calls than your key allows any extra calls will fail and may result in your application not functioning.
- How do I get production access for my key?
Keys on our charity and event package are issued with access to only our sandbox environment. We ask that you develop your applications using test calls to the sandbox until you feel it is ready for public use.
When you're ready to start using our production environment, please contact us with the subject of 'Production access request'. We'll require final confirmation of the following:
- Name of your application
- A link to where your application will be deployed
- Full description of how your application will be used (please provide as much detail as possible)
- Your callback URL (only needed if you're developing with our account and page creation APIs)
- The name of the organisation your application is for (if you're developing on behalf of someone)
- Whether your application requires a higher rate limit than your API key currently offers
We'll only be able to provide production access once we have this information. We'll review your application during business hours (Monday to Friday, 9.00am to 5.30pm) and we'll confirm by email when your key has been upgraded or ask you for any further information to assess your request.
- What are IO Docs?
Once you have an API key you can use IO Docs to make test calls against our sandbox environment.
This interactive resource can really help speed up your development as you can construct new calls by entering individual parameters, seeing the completed call URL and results of your calls instantly. You'll just need to amend the sandbox calls made in IO Docs to point to our production environment when your application is ready for live.
- What is the Virgin Money Giving sandbox?
We have provided a test version of the Virgin Money Giving site to help you develop with our APIs. You can use the sandbox site just like the live site to create new fundraiser accounts and pages at http://uk.sandbox.virginmoneygiving.com.
You can also create and gather data from the sandbox with API calls in the same way as live, just from a different location. API calls made to our sandbox environment begin https://sandbox.api.virginmoneygiving.com
Data is never shared between sandbox and live environments so you won't be able to find live cases in the sandbox and vice versa.
Please remember that other developers can see the test cases you create in the sandbox and we reserve the right to remove any that may cause offence. As a test environment we will also clear the database from time to time so it's worth keeping a backup of your test data if you need it.
- How do I add a charity or event to the sandbox?
If you need a specific new charity or event test case to be added to the sandbox, please contact us with your requirements and we'll create them for you.
- What is a callback URL?
A callback URL is required when you want to set up fundraising pages using APIs. This feature is available as part of our charity and event packages. You'll be asked whether you want to specify a callback URL when you register a new application or update an existing one. It must be a secure (https) website and will be used to provide you with an access token to create a fundraising page for a specific account. The access token will be sent to your callback URL when you create a fundraiser account or when you request an access token from our authentication API.
- How can I increase the rate limits on my keys?
If you're getting alerts about your rate limits or expecting to exceed your key rate limit when your application goes live, please contact us to discuss your requirements, we're keen to help. You'll be sent an alert to the email address you used to register your application if you are nearing your daily call limit and another if you exceed your per second or per day limit.
It's also worth considering what you can do to make your rate limit go further, for example if you're returning data for a popular web page, think about caching your requests rather than calling the API each time the page loads.
- How can I check the status of my API keys?
By signing into your account and selecting 'My keys' you will see all the keys linked to your developer account. This information will include a status of either 'active' or 'waiting'. An 'active' key is ready to use while a 'waiting' key requires authorisation before it can be used. We moderate key requests when multiple keys have been requested for the same API packages. We review and activate keys during normal business hours (Mon - Fri, 9am - 5.30pm).
- How do I update my developer account details?
By signing into your account and selecting 'Manage Account' you will be able to update your contact information including links to our own website and blog. You will also find links to update your email address, password and manage your public profile information.
- How do I update my application details?
It's important you keep your application details up to date as it lets us know what its purpose is and where it is in use on the web. We actively monitor our APIs and will look for any information you give regarding your application to be accurate.
By signing in to your account and selecting 'Applications' you will be able to view any applications you have created. You will see links within each application to 'Edit' the information held for that application or to 'Delete Application' if you wish to remove the application from your account.
- How do I delete my developer account?
If you wish to delete your Virgin Money Giving developer account, sign nto your account and select 'Manage Account'. From here you will see a link to 'Delete my Virgin Money Giving developer account'. After selecting this option and confirming your intention your account will be deleted and any active keys will cease to function.
- Which browsers do you support?
We recommend using the latest version of your preferred browser to view this site. If you have any difficulty using the site and are on the latest version, please contact us and we'll be happy to investigate.