NAV
curl Ruby Python

Introduction


 _____  _      ______ _____   _____ ______ _      _____ _   _  _____
|  __ \| |    |  ____|  __ \ / ____|  ____| |    |_   _| \ | |/ ____|
| |__) | |    | |__  | |  | | |  __| |__  | |      | | |  \| | |  __
|  ___/| |    |  __| | |  | | | |_ |  __| | |      | | | . ` | | |_ |
| |    | |____| |____| |__| | |__| | |____| |____ _| |_| |\  | |__| |
|_|    |______|______|_____/ \_____|______|______|_____|_| \_|\_____|

                                _____  _____
                         /\    |  __ \|_   _|
                        /  \   | |__) | | |
                       / /\ \  |  ___/  | |
                      / ____ \ | |     _| |_
                     /_/    \_\|_|    |_____|

Welcome to Pledgeling’s API!

The Pledgeling API allows you to seamlessly integrate global charity search and donation processing into your online platforms. Offer your users the ability to search for their favorite charities around the world by name, location or cause directly through your site. Through our flexible API you have complete control over the user experience and can allow your users to donate in a variety of ways, including the ability to round-up their transaction for charity, enter their own donation amount, or have preset donation options to choose from.

We have language examples in curl, Ruby, and Python!

Want to connect with our team about using Pledgeling’s API in your platform? Email dev@pledgeling.com

Authentication

To authorize, pass the API key in the authorization headers:

# With shell, you can just pass the correct header with each request
curl "https://api.pledgeling.com/v1/donations" \
  -H "Authorization: Bearer {api_key}"
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledgeling.com/v1/donations",
  headers
)
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledgeling.com/v1/donations",
  headers=headers
  )

Make sure to replace {api_key} with your API key.

Pledgeling uses API keys to allow access to the API. If you do not have a partner account, please contact us here to get started.

An API key is required in all API requests. Use the Authorization header with the following format:

Authorization: Bearer {api_key}

Pagination

Example Response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledgeling.com/v1/donations",
  "next": "https://api.pledgeling.com/v1/donations?page=2",
  "previous": null,
  "total_count": 2,
  "results": [
    {
      "id": "0f69319c-9321-4531-ad52-6cb87a292d35",
      "user_id": "0854c837-b204-4ba0-8b39-238cb40ca7e9",
      "email": "btyrese@gmail.com",
      "first_name": "Brock",
      "last_name": "Tyrese",
      "organization_id": "3685b542-61d5-45da-9580-162dca725966",
      "organization_name": "American Red Cross",
      "amount": "0.25",
      "phone_number": "+13235550107",
      "status": "processed",
      "metadata": "arbitrary data string",
      "created_at": "2016-01-01T12:00:00Z",
      "updated_at": "2016-01-01T12:00:00Z"
    },
    {
      "id": "596599ba-1737-49dd-89ea-bbf66552b46d",
      "user_id": "75c78e7c-0ed9-4ce3-9f4a-a2c1abe9584d",
      "email": "celestina_k@aol.com",
      "first_name": "Celestina",
      "last_name": "Keshia",
      "organization_id": "ec0b21fc-2671-431e-8a81-783b7a9626c9",
      "organization_name": "Surfrider Foundation",
      "amount": "250",
      "phone_number": "+12125550196",
      "status": "processed",
      "metadata": "you can put whatever you like here",
      "created_at": "2016-01-01T12:00:00Z",
      "updated_at": "2016-01-01T12:00:00Z"
    },
    ...
  ]
}

All resource lists are paginated.

The collection of records can be traversed by following the next/previous links provided or by specifying the page parameter to jump to a specific page number.

Attribute Description
page
Integer
The current page number.
per
Integer
Number of records per page.
uri
String
The current request’s link.
next
String
Link to the next page.
previous
String
Link to the previous page.
total_count
Integer
Total number of records. If filter criteria are specified, only records that match the criteria are counted.
results
Resources Array
An array of resources on the current page.

Donations

Before you can use the API, you need to decide which nonprofit(s) you would like to support. You can support as many or as few nonprofits as you like. You can also let your users choose which nonprofit they wish to support by integrating our Nonprofit Search API.

When a donation is made, you process the payment as you normally would, and make the API call to Pledgeling with the donation information. We’ll take it from there; including sending the tax receipt to the donor and disbursing the funds to the nonprofit.

Donation Resource

Example Donation Response

{
  "id": "0f69319c-9321-4531-ad52-6cb87a292d35",
  "user_id": "0854c837-b204-4ba0-8b39-238cb40ca7e9",
  "email": "btyrese@gmail.com",
  "first_name": "Brock",
  "last_name": "Tyrese",
  "organization_id": "3685b542-61d5-45da-9580-162dca725966",
  "organization_name": "American Red Cross",
  "amount": "0.25",
  "phone_number": "+13235550107",
  "status": "processed",
  "metadata": "arbitrary data string",
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}
Attribute Description
id
String
Unique identifier.
user_id
String
Unique identifier of the user resource, unique per email address.
email
String
Your user’s email address.
first_name
String
Your user’s first name.
last_name
String
Your user’s last name.
organization_id
String
Unique identifier of the organization resource.
organization_name
String
Name of the non-profit organization.
amount
Decimal
Donation amount.
phone_number
String
Your user’s phone number, defaults to US country code and in E.164 format.
status
String
Status of the donation processing.

Possible values:
pendingprocessedcancelled
metadata
String
Metadata you may wish to store along with the donation (eg. “External ID: 0999”).
created_at
Datetime String
Resource created at time in UTC timezone and in ISO-8601 format.
updated_at
Datetime String
Resource updated at time in UTC timezone and in ISO-8601 format.

List All Donations

curl "https://api.pledgeling.com/v1/donations" \
  -H "Authorization: Bearer {api_key}"
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledgeling.com/v1/donations",
  headers
)
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledgeling.com/v1/donations",
  headers=headers
  )

Example Response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledgeling.com/v1/donations",
  "next": null,
  "previous": null,
  "total_count": 2,
  "results": [
    {
      "id": "0f69319c-9321-4531-ad52-6cb87a292d35",
      "user_id": "0854c837-b204-4ba0-8b39-238cb40ca7e9",
      "email": "btyrese@gmail.com",
      "first_name": "Brock",
      "last_name": "Tyrese",
      "organization_id": "3685b542-61d5-45da-9580-162dca725966",
      "organization_name": "American Red Cross",
      "amount": "0.25",
      "phone_number": "+13235550107",
      "status": "processed",
      "metadata": "arbitrary data string",
      "created_at": "2016-01-01T12:00:00Z",
      "updated_at": "2016-01-01T12:00:00Z"
    },
    {
      "id": "596599ba-1737-49dd-89ea-bbf66552b46d",
      "user_id": "75c78e7c-0ed9-4ce3-9f4a-a2c1abe9584d",
      "email": "celestina_k@aol.com",
      "first_name": "Celestina",
      "last_name": "Keshia",
      "organization_id": "ec0b21fc-2671-431e-8a81-783b7a9626c9",
      "organization_name": "Surfrider Foundation",
      "amount": "250",
      "phone_number": "+12125550196",
      "status": "processed",
      "metadata": "you can put whatever you like here",
      "created_at": "2016-01-01T12:00:00Z",
      "updated_at": "2016-01-01T12:00:00Z"
    }
  ]
}

List of all donations.

HTTP Request

GET https://api.pledgeling.com/v1/donations

Parameters

Parameter Description
first_name
String
Optional
Filter results by user’s first name, which contains the provided substring.
last_name
String
Optional
Filter results by user’s last name, which contains the provided substring.
user_id
String
Optional
Filter results by user’s unique identifier.
email
String
Optional
Filter results by user’s email, which contains the provided substring.
phone_number
String
Optional
Filter results by user’s phone number, which contains the provided substring.
status
String
Optional
Filter results by donation processing status.

Accepted values:
pendingprocessedcancelled
start_date
String
Optional
Filter results by start date, in format of YYYY-MM-DD.
end_date
String
Optional
Filter results by end date, in format of YYYY-MM-DD.
organization_id
String
Optional
Filter results by non-profit organization’s unique identifier.
organization_name
String
Optional
Filter results by non-profit organization’s name.
page
Integer
Optional
Page number.

Retrieve Donation Details

curl "https://api.pledgeling.com/v1/donations/0f69319c-9321-4531-ad52-6cb87a292d35" \
  -H "Authorization: Bearer {api_key}"
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledgeling.com/v1/donations/0f69319c-9321-4531-ad52-6cb87a292d35",
  headers
)
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledgeling.com/v1/donations/0f69319c-9321-4531-ad52-6cb87a292d35",
  headers=headers
  )

Example Response

{
  "id": "0f69319c-9321-4531-ad52-6cb87a292d35",
  "user_id": "0854c837-b204-4ba0-8b39-238cb40ca7e9",
  "email": "btyrese@gmail.com",
  "first_name": "Brock",
  "last_name": "Tyrese",
  "organization_id": "3685b542-61d5-45da-9580-162dca725966",
  "organization_name": "American Red Cross",
  "amount": "0.25",
  "phone_number": "+13235550107",
  "status": "processed",
  "metadata": "arbitrary data string",
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Retrieve details of a donation.

HTTP Request

GET https://api.pledgeling.com/v1/donations/{id}

Create a Donation

curl "https://api.pledgeling.com/v1/donations" \
  -X POST \
  -H "Authorization: Bearer {api_key}" \
  -F "email=yjh@ok.gov" \
  -F "first_name=Yvonne" \
  -F "last_name=Hilda" \
  -F "organization_id=dd959794-d83f-4128-be24-651d2a398f12" \
  -F "amount=0.68" \
  -F "phone_number=(918) 555-0188" \
  -F "metadata=external_id+870203745"
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.post(
  "https://api.pledgeling.com/v1/donations",
  {
    email: "yjh@ok.gov",
    first_name: "Yvonne",
    last_name: "Hilda",
    organization_id: "dd959794-d83f-4128-be24-651d2a398f12",
    amount: "0.68",
    phone_number: "(918) 555-0188",
    metadata: "external_id 870203745",
  },
  headers
)
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.post(
  "https://api.pledgeling.com/v1/donations",
  data={
    "email": "yjh@ok.gov",
    "first_name": "Yvonne",
    "last_name": "Hilda",
    "organization_id": "dd959794-d83f-4128-be24-651d2a398f12",
    "amount": "0.68",
    "phone_number": "(918) 555-0188",
    "metadata": "external_id 870203745"
    },
  headers=headers
  )

Example Response

{
  "id": "940ff61f-91d1-4dce-98d2-cf1b1284793c",
  "user_id": "d913d990-3627-4cdf-b21b-e5dffc91bcc2",
  "email": "yjh@ok.gov",
  "first_name": "Yvonne",
  "last_name": "Hilda",
  "organization_id": "dd959794-d83f-4128-be24-651d2a398f12",
  "organization_name": "Water.org",
  "amount": "0.68",
  "phone_number": "+19185550188",
  "status": "processed",
  "metadata": "external_id 870203745",
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Create a donation to a non-profit organization in your user’s name.

If your partner wallet does not have sufficient funds to cover the donation amount, the create donation request will return unprocessable entity error and donation will be updated with cancelled status.

HTTP Request

POST https://api.pledgeling.com/v1/donations

Parameters

Parameter Description
email
String
User’s email address.
first_name
String
User’s first name.
last_name
String
User’s last name.
organization_id
String
Non-profit organization’s unique identifier.
amount
Decimal String
Donation amount.
phone_number
String
Optional
User’s phone number.

Sample values:
(918) 555-01889185550188
metadata
String
Optional
Custom metadata.

Sample values:
Christmas fundraiser donationExternal ID: 5554

Organizations

The Organizations API allows you to search our database of non-governmental organizations.

Organization Resource

Example Organization Response

{
  "id": "3685b542-61d5-45da-9580-162dca725966",
  "name": "American Red Cross",
  "alias": "",
  "ngo_id": "53-0196605",
  "mission": "The American Red Cross prevents and alleviates human suffering in the face of emergencies by mobilizing the power of volunteers and the generosity of donors.",
  "street1": "2025 E Street, NW",
  "street2": "",
  "city": "Washington",
  "region": "DC",
  "postal_code": "20006",
  "country": "US",
  "lat": "-77.041248",
  "lon": "38.897131",
  "website_url": "http://www.redcross.org/",
  "profile_url": "https://www.pledgeling.com/organizations/42/american-red-cross",
  "logo_url": "https://res.cloudinary.com/pledgeling/w_266%2Ch_266%2Cc_fit/prod-media/images%2Fnpos%2Flogos%2F2017%2F2%2F6%2FARC_Logo_Bttn_HorizStkd_RGB.png"
}
Attribute Description
id
String
Unique identifier.
name
String
Organization name.
alias
String
Organization’s common/abbreviated name, if available.
ngo_id
String
Recognized NGO ID (EIN, Registered Charity ID, etc) for the organization.
mission
String
Mission statement.
street1
String
Street address line 1.
street2
String
Street address line 2.
city
String
Address city name.
region
String
Address region.

For US addresses, includes 50 U.S. states, DC (District of Columbia), PR (Puerto Rico), and VI (Virgin Islands).
postal_code
String
Address postal/zip code.
country
String
ISO 3166-1 2 character Country Code.
lat
String
Address latitude.
lon
String
Address longitude.
cause
String
Cause name.
website_url
String
Website URL.
profile_url
String
Pledgeling profile URL.
logo_url
String
Logo URL.

List All Organizations

curl "https://api.pledgeling.com/v1/organizations" \
  -H "Authorization: Bearer {api_key}"
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledgeling.com/v1/organizations",
  headers
)
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledgeling.com/v1/organizations",
  headers=headers
  )

Example Response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledgeling.com/v1/organizations",
  "next": null,
  "previous": null,
  "total_count": 2,
  "results": [
    {
      "id": "3685b542-61d5-45da-9580-162dca725966",
      "name": "American Red Cross",
      "alias": "",
      "ngo_id": "53-0196605",
      "mission": "The American Red Cross prevents and alleviates human suffering in the face of emergencies by mobilizing the power of volunteers and the generosity of donors.",
      "street1": "2025 E Street, NW",
      "street2": "",
      "city": "Washington",
      "region": "DC",
      "postal_code": "20006",
      "country": "US",
      "lat": "-77.041248",
      "lon": "38.897131",
      "website_url": "http://www.redcross.org/",
      "profile_url": "https://www.pledgeling.com/organizations/42/american-red-cross",
      "logo_url": "https://res.cloudinary.com/pledgeling/w_266%2Ch_266%2Cc_fit/prod-media/images%2Fnpos%2Flogos%2F2017%2F2%2F6%2FARC_Logo_Bttn_HorizStkd_RGB.png"
    },
    {
      "id": "ec0b21fc-2671-431e-8a81-783b7a9626c9",
      "name": "Surfrider Foundation",
      "alias": "",
      "ngo_id": "95-3941826",
      "mission": "The Surfrider Foundation is a non-profit, grassroots organization dedicated to the protection and enjoyment of our world’s oceans, waves and beaches through a powerful activist network. Founded in 1984 by a handful of visionary surfers in Malibu, California, the Surfrider Foundation now maintains more than 250,000 supporters, activists and members worldwide.",
      "street1": "PO Box 6010",
      "street2": "",
      "city": "San Clemente",
      "region": "CA",
      "postal_code": "92674",
      "country": "US",
      "lat": "-117.623131",
      "lon": "33.438428",
      "website_url": "http://www.surfrider.org/",
      "profile_url": "https://www.pledgeling.com/organizations/718/surfrider-foundation",
      "logo_url": "https://res.cloudinary.com/pledgeling/w_266%2Ch_266%2Cc_fit/prod-media/images%2Fnpos%2Flogos%2Fbatched%2F718.jpg"
    }
  ]
}

List of all organizations.

HTTP Request

GET https://api.pledgeling.com/v1/organizations

Parameters

Parameter Description
q
String
Optional
Filter results by searching for keyword matches on organization name/alias/mission fields.
ngo_id
String
Optional
Filter results by NGO ID (such as EIN for US based non-profits).
region
String
Optional
Filter results by region.

For US based non-profits, accepted values include 50 U.S. states, DC (District of Columbia), PR (Puerto Rico), and VI (Virgin Islands).
postal_code
String
Optional
Filter results by postal/zip code.
country
String
Optional
Filter results by ISO 3166-1 2 character Country Code.
cause_id
String
Optional
Filter results by cause. Contact support@pledgeling.com for list of causes.
lat
String
Optional
Filter results by proximity of a geographic point (latitude). Must be paired with lon.

When specified, results will be returned in order of nearest.
lon
String
Optional
Filter results by proximity of a geographic point (longitude). Must be paired with lat.

When specified, results will be returned in order of nearest.
page
Integer
Optional
Page number.

Retrieve Organization Details

curl "https://api.pledgeling.com/v1/organizations/3685b542-61d5-45da-9580-162dca725966" \
  -H "Authorization: Bearer {api_key}"
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledgeling.com/v1/organizations/3685b542-61d5-45da-9580-162dca725966",
  headers
)
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledgeling.com/v1/organizations/3685b542-61d5-45da-9580-162dca725966",
  headers=headers
  )

Example Response

{
  "id": "3685b542-61d5-45da-9580-162dca725966",
  "name": "American Red Cross",
  "alias": "",
  "ngo_id": "53-0196605",
  "mission": "The American Red Cross prevents and alleviates human suffering in the face of emergencies by mobilizing the power of volunteers and the generosity of donors.",
  "street1": "2025 E Street, NW",
  "street2": "",
  "city": "Washington",
  "region": "DC",
  "postal_code": "20006",
  "country": "US",
  "lat": "-77.041248",
  "lon": "38.897131",
  "website_url": "http://www.redcross.org/",
  "profile_url": "https://www.pledgeling.com/organizations/42/american-red-cross",
  "logo_url": "https://res.cloudinary.com/pledgeling/w_266%2Ch_266%2Cc_fit/prod-media/images%2Fnpos%2Flogos%2F2017%2F2%2F6%2FARC_Logo_Bttn_HorizStkd_RGB.png"
}

Retrieve details of an organization.

HTTP Request

GET https://api.pledgeling.com/v1/organizations/{id}

Errors

The Pledgeling API uses the following HTTP status codes:

Status Code Meaning
200 OK – The request completed successfully.
201 Created – The post request created the resource successfully.
202 Accepted – The request is placed on our task queues to be processed and have not yet completed.
400 Bad Request – The request could not be completed due to wrong parameters.
401 Unauthorized – You provided an invalid API key.
404 Not Found – The requested API does not exist.
422 Unprocessable Entity – The valid request failed to complete successfully on our servers.
500 Internal Server Error – We had a problem with our server. Try again later.