Charity Search

Charity Search Integration Guide

DOCS

Last updated: Sept 24th, 4:20pm

The Charity Search API is a PayPal limited release REST API that you can use in conjunction with other publicly available external APIs.

Overview

Partners can use the Charity Search API to list charities registered with the PayPal Giving Fund (PPGF). Partners can use the API response to offer giving programs to their customers.

When you list charities, you can specify optional query parameters to filter the search response. Some query parameters return an exact match while others return the closest matches. You can also combine different query parameters in a search or use a particular keyword across all descriptive and key fields of a charity in a search.

The API supports the following types of searches:

  • Exact match search

    Search by ID, employer identification number (EIN), country code, postal code, or email address.

  • Broad match search

    Search by a word or phrase in the description, name, keywords, or mission for the charity.

For details, see the Charity Search Limited Release API Reference.

Integration steps
1. Required Set up your development environment.
2. Required List charities.
3. Optional Create charity search query.

Set up your development environment

Before you can integrate Charity Search, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Charity Search.

List charities

You can specify optional query parameters to filter the search response. This sample request lists charities with names that contain Nicholas in the 78704 zip code in the United States:

    1curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/charities?nonprofit_id=12345&payer_id=AFGJ8734PA&name=Nicholas Orthodox Church&ein=840004372&email=charity@example.com&description=local&charity_type=PPGF&confirmed_status=CONFIRMED&giving_fund_status=ACTIVE®istration_date=2015-07-11&last_modified_date=2015-09-11&keywords=Christian&mission_area=Humanities&state=TX&country_code=US&postal_code=78704&search_all=Church&page_size=1&page=3&total_required=true&latitude=51.500729&longitude=-0.124625&distance_units=miles&radius=1000 \
    2  -H "Content-Type: application/json" \
    3  -H "Authorization: Bearer <Access-Token>"

    The response lists the St. Nicholas Fund located in Austin, TX. The response also includes the total_items and total_pages fields because the request specified the total_required=true query parameter:

      1{
      2  "total_items": 5,
      3  "total_pages": 5,
      4  "results": [
      5  {
      6    "nonprofit_id": "12345",
      7    "payer_id": "AFGJ8734PA",
      8    "name": "St. Nicholas Fund",
      9    "ein": "840004372",
      10    "email": "charity@example.com",
      11    "description": "Support numerous local non-profit organizations.",
      12    "confirmed_status": "CONFIRMED",
      13    "giving_fund_status": "ACTIVE",
      14    "registration_date": "2015-07-11",
      15    "confirmation_date": "2015-08-11",
      16    "last_modified_date": "2015-09-11",
      17    "keywords": "Christian,OCA,non-profit",
      18    "slogan": "Give",
      19    "website_url": "https://example.com",
      20    "logo_url": "https://example.com/logos/logo.gif",
      21    "mission_area": [
      22    {
      23      "primary": true,
      24      "name": "Arts and Humanities"
      25    }],
      26    "contact": [
      27    {
      28      "email": "contact@example.com"
      29    }],
      30    "address":
      31    {
      32      "line1": "123 Main St.",
      33      "line2": "#3",
      34      "city": "Austin",
      35      "state": "TX",
      36      "country_code": "US",
      37      "postal_code": "78704"
      38    },
      39    "links": [
      40    {
      41      "href": "https://api-m.sandbox.paypal.com/v1/customer/charities?nonprofit_id=12345",
      42      "rel": "self",
      43      "method": "GET"
      44    }]
      45  }],
      46  "links": [
      47  {
      48    "href": "https://api-m.sandbox.paypal.com/v1/customer/charities?total_required=true&page_size=1&page=3",
      49    "rel": "self",
      50    "method": "GET"
      51  },
      52  {
      53    "href": "https://api-m.sandbox.paypal.com/v1/customer/charities?total_required=true&page_size=1&page=1",
      54    "rel": "first",
      55    "method": "GET"
      56  },
      57  {
      58    "href": "https://api-m.sandbox.paypal.com/v1/customer/charities?total_required=true&page_size=1&page=2",
      59    "rel": "prev",
      60    "method": "GET"
      61  },
      62  {
      63    "href": "https://api-m.sandbox.paypal.com/v1/customer/charities?total_required=true&page_size=1&page=4",
      64    "rel": "next",
      65    "method": "GET"
      66  },
      67  {
      68    "href": "https://api-m.sandbox.paypal.com/v1/customer/charities?total_required=true&page_size=1&page=5",
      69    "rel": "last",
      70    "method": "GET"
      71  }]
      72}

      Create charity search query

      You can create a charity search query. Include the filter criteria for the query in the JSON request body:

        1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/charity-search-queries \
        2  -H "Content-Type: application/json" \
        3  -H "Authorization: Bearer <Access-Token>" \
        4  -d '{
        5  "charity":
        6  {
        7    "nonprofit_id": "12345",
        8    "payer_id": "AFGJ8734PA",
        9    "name": "Nicholas Orthodox Church",
        10    "ein": "840004372",
        11    "email": "charity@example.com",
        12    "charity_type": "PPGF",
        13    "confirmed_status": "CONFIRMED",
        14    "giving_fund_status": "ACTIVE",
        15    "registration_date": "2015-07-11",
        16    "last_modified_date": "2015-09-11",
        17    "keywords": "Christian",
        18    "mission_area": "Humanities"
        19  },
        20  "search_all": "Church",
        21  "page_size": 15,
        22  "total_required": true
        23}'

        The response includes a query ID that you can use to list charities that meet the query criteria. The lifetime of the query is three hours.

          1{
          2  "query_id": "ASDFGHJIJ",
          3  "charity":
          4  {
          5    "nonprofit_id": "12345",
          6    "payer_id": "AFGJ8734PA",
          7    "name": "Nicholas Orthodox Church",
          8    "ein": "840004372",
          9    "email": "charity@example.com",
          10    "description": "local",
          11    "charity_type": "PPGF",
          12    "confirmed_status": "CONFIRMED",
          13    "giving_fund_status": "ACTIVE",
          14    "registration_date": "2015-07-11",
          15    "last_modified_date": "2015-09-11",
          16    "keywords": "Christian",
          17    "mission_area": "Humanities",
          18    "address":
          19    {
          20      "state": "US-TX",
          21      "country_code": "US",
          22      "postal_code": "78704"
          23    }
          24  },
          25  "search_all": "Church",
          26  "page_size": 15,
          27  "total_required": true,
          28  "links": [
          29  {
          30    "href": "https://api-m.sandbox.paypal.com/v1/customer/charity-search-queries/ASDFGHJIJ",
          31    "rel": "self",
          32    "method": "GET"
          33  },
          34  {
          35    "href": "https://api-m.sandbox.paypal.com/v1/customer/charities?query_id=ASDFGHJIJ",
          36    "rel": "charities",
          37    "method": "GET"
          38  }]
          39}

          Additional information

          ReferencePayPal.comPrivacyCookiesSupportLegalContact

          If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more