Charity search

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

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."
  }
 ]
}