Charity search

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

Charity search

This API can be used to allow a fundraiser to select a charity or charities to fundraise for, when creating a fundraising page.

This API allows a search to be performed using a partial charity name. The API will return all charities that contain the search value within their name.

This will only return charities that are available in the VMG website, i.e. those that have completed their application and all the checks required to fundraise on VMG.

The maximum number of charities returned is 100.

URL

Operation type: GET

https://api.virginmoneygiving.com/charities/v1/search?name={charity name}&api_key={your API key}

Parameter Required Data type Description
name True Varchar(50) Partial or full charity name.
api_key True Varchar(24) This is your key that allows you access to the VMG APIs.

Response

Outcome Further information
Success

If a live charity or charities match the search criteria the following is returned:

  • Status 200: OK

List of matching charities from the search service, in the following format:

  • Name
  • Charity resource ID
  • Link to charity account
  • Charity description
Error

Sample error:

If no charities match the search criteria the following is returned:

  • Error code: 001.01.002
  • Error message: No matching charity found for {charity}

Click here for a full list of API error codes.

Response description

Parameter Data type Description
name Varchar(152) Name of the charity.
resourceId Varchar(36) This is the resource ID of the charity.
charityURI Varchar(100) A link to their charity account via our API.
description Varchar(1000) A description of the charity.

XML response example

<charities>
  <charity>
   <name>Test charity</name>
   <resourceId>0531db22-8d5f-11e2-ad62-005056a8589d</resourceId>
   <description>Test charity info here.</description>
   <charityURI>https://sandbox.api.virginmoneygiving.com/charities/v1/0531db22-8d5f-11e2-ad62-005056a8589d</charityURI>
  </charity>
</charities>

JSON response example

{
{
 "message": null,
 "charities":
 [
  {
   "name": "Test charity",
   "resourceId": "0531db22-8d5f-11e2-ad62-005056a8589d",
   "charityURI": "sandbox.api.virginmoneygiving.com/charities/v1/account/0531db22-8d5f-11e2-ad62-005056a8589d",
   "description": "Test charity info here."
  }
 ]
}

version 34 as of 1 year ago by marc