API Documentation

8888888b.  888               888
888   Y88b 888               888
888    888 888               888
888   d88P 888  .d88b.   .d88888  .d88b.   .d88b.
8888888P"  888 d8P  Y8b d88" 888 d88P"88b d8P  Y8b
888        888 88888888 888  888 888  888 88888888
888        888 Y8b.     Y88b 888 Y88b 888 Y8b.
888        888  "Y8888   "Y88888  "Y88888  "Y8888
                                      888
                                 Y8b d88P
       d8888 8888888b. 8888888    "Y88P"
      d88888 888   Y88b  888
     d88P888 888    888  888
    d88P 888 888   d88P  888  .d8888b
   d88P  888 8888888P"   888  88K
  d88P   888 888         888  "Y8888b.
 d8888888888 888         888       X88
d88P     888 888       8888888 88888P'

Welcome to Pledge’s API Documentation!

Pledge’s APIs allow 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.

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

Want to connect with our team about using Pledge’s APIs in your platform? Create an account to gain access to Pledge APIs.

REST API

Getting started

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.

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.pledge.to/v1/donations" \
  -H "Authorization: Bearer {api_key}"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledge.to/v1/donations",
  headers
)

import requests

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

Pledge uses API keys to allow access to the API. You can find your API Key in the Integrations section on your account.

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

Authorization: Bearer {api_key}

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

Pagination

Example response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledge.to/v1/donations",
  "next": "https://api.pledge.to/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",
      "external_id": "439087218",
      "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",
      "external_id": "",
      "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.

Response codes

The Pledge 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.

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 Pledge 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 resource

{
  "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",
  "external_id": "439087218",
  "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: •`pending` •`processed` •`canceled`
external_id String	An optional identifier that you can provide to tag a collection of donations. Can be used in conjunction with Impact Calculators.
metadata String	Metadata you may wish to store along with the donation (eg. "Shopify 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.pledge.to/v1/donations" \
  -H "Authorization: Bearer {api_key}"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledge.to/v1/donations",
  headers
)

import requests

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

Example response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledge.to/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",
      "external_id": "439087218",
      "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",
      "external_id": "",
      "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.pledge.to/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.
status String Optional	Filter results by donation processing status. Accepted values: •`pending` •`processed` •`canceled`
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.
is_anonymous Boolean Optional	Filter results by whether donations are anonymous.
page Integer Optional	Page number.

Retrieve donation details

curl "https://api.pledge.to/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.pledge.to/v1/donations/0f69319c-9321-4531-ad52-6cb87a292d35",
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledge.to/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",
  "external_id": "439087218",
  "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.pledge.to/v1/donations/{id}

Create a donation

curl "https://api.pledge.to/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=shopify_id+870203745"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.post(
  "https://api.pledge.to/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: "shopify_id 870203745",
  },
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.post(
  "https://api.pledge.to/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": "shopify_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",
  "external_id": "439087218",
  "metadata": "shopify_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.

In order to process donations, you need to set up a credit card in the Impact Hub. Note: If you are a prepaid partner and 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 canceled status.

HTTP request

POST https://api.pledge.to/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-0188` •`9185550188`
external_id String Optional	An identifier to tag donations for a specific Impact Calculator
metadata String Optional	Custom metadata. Sample values: •`Christmas fundraiser donation` •`External ID: 5554`
send_tax_receipt Boolean Optional	Sends a donation tax receipt to the donor's email if set to `true`. Default is `false`

Fundraisers

Fundraisers are embeddable donation forms that are used to raise money for nonprofits or personal causes (crowdfunding).

Fundraiser resource

Example fundraiser resource

{
  "id": "",
  "start_time": "2019-05-04 03:00:00 UTC",
  "end_time": "2019-05-04 05:00:00 UTC",
  "goal": "1500.0",
  "total_raised": "128.22",
  "total_donors": "7",
  "beneficiary": {
    "type": "Organization",
    "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",
    "causes": [
      {
        "id": 73,
        "name": "Disaster Relief",
        "parent_id": null
      },
      {
        "id": 91,
        "name": "Society",
        "parent_id": null
      }
    ],
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/organizations/53-0196605/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",
    "disbursement_type": "standard"
    "impact_metrics": [],
    "sustainable_development_goals": [
      {
        "id": 3,
        "name": "good health and well-being"
      },
      {
        "id": 10,
        "name": "reduced inequalities"
      },
      {
        "id": 15,
        "name": "life on land"
      },
      {
        "id": 16,
        "name": "peace, justice and strong institutions"
      },
      {
        "id": 17,
        "name": "partnerships for the goals"
      }
    ],
  },
  "organizers": [
    {
      "id": "okn6IpWQSNof_JWCMarFSw",
      "email": "sam@pledge.to",
      "first_name": "Sam",
      "last_name": "Goldstein"
    }
  ],
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Attribute	Description
id String	Unique identifier.
start_time Datetime String	Time event starts in UTC timezone and in ISO-8601 format.
end_time Datetime String	Time event ends in UTC timezone and in ISO-8601 format.
goal Decimal	Amount you want to raise for this fundraiser.
total_raised Decimal	Amount currently raised for this fundraiser.
total_donors Integer	Number of donations made to this fundraiser.
beneficiary Object	Representation of an organization with an added `type` attribute or a crowdfunding campaign.
organizers Object Array	Collection of objects representing users organizing the fundraiser.
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.

Crowdfund beneficiary resource

Attribute	Description
type String	Type of beneficiary.
purpose String	Name of crowdfunding campaign.

Organizer user resource

Attribute	Description
id String	Unique identifier for user.
email String	Your user’s email address.
first_name String	Your user’s first name.
last_name String	Your user’s last name.

Retrieve fundraiser details

curl "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg" \
  -H "Authorization: Bearer {api_key}"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg",
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg",
  headers=headers
  )

Example response

{
  "id": "",
  "start_time": "2019-05-04 03:00:00 UTC",
  "end_time": "2019-05-04 05:00:00 UTC",
  "goal": "1500.0",
  "total_raised": "128.22",
  "total_donors": "7",
  "beneficiary": {
    "type": "Organization",
    "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",
    "causes": [
      {
        "id": 73,
        "name": "Disaster Relief",
        "parent_id": null
      },
      {
        "id": 91,
        "name": "Society",
        "parent_id": null
      }
    ],
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/organizations/53-0196605/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",
    "disbursement_type": "standard"
    "impact_metrics": [],
    "sustainable_development_goals": [
      {
        "id": 3,
        "name": "good health and well-being"
      },
      {
        "id": 10,
        "name": "reduced inequalities"
      },
      {
        "id": 15,
        "name": "life on land"
      },
      {
        "id": 16,
        "name": "peace, justice and strong institutions"
      },
      {
        "id": 17,
        "name": "partnerships for the goals"
      }
    ],
  },
  "organizers": [
    {
      "id": "okn6IpWQSNof_JWCMarFSw",
      "email": "sam@pledge.to",
      "first_name": "Sam",
      "last_name": "Goldstein"
    }
  ],
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Retrieve details of a fundraiser.

HTTP request

GET https://api.pledge.to/v1/fundraisers/{id}

Creating/updating fundraisers

Creating (POST) and Updating (PATCH) vs. Placing (PUT) — Which one(s) should you use?

POST only creates new fundraisers. When using POST, specifying an ID is optional. If an ID is not spcified, one is generated for you and it is up to you to save it in order to reference your fundraiser in the future. If you specify an ID that has already been taken, the fundraiser will fail to create and an error message will be returned.

PATCH only updates existing fundraisers. Specifying an ID is required to use PATCH. If a fundraiser does not exist with the given ID, the request will fail and return an error. PATCH will work with your IDs or autogenerated ones. PATCH will accept partial updates where only the attributes that are specified will be updated.

PUT can create new fundraisers or overwrite existing ones. Specifying an ID is required to use PUT and is idempotent, so unless there is an error in your data, it should always work. If a fundraiser exists with the given ID, it will be overwritten. If it does not, it will be created. PUT will work with your IDs or autogenerated ones. Important: parameters sent to PUT must be complete. Unlike PATCH, partial updates will reset all unspecified attributes for the fundraiser.

Use POST and PATCH if you want to be specific when creating or updating fundraisers and want to get an error message when trying to overwrite existing fundraisers or update non-existant fundraisers. Use PUT if you don’t care about overwriting existing fundraisers and want guarenteed success with valid parameters.

Note: the ID is specified as a parameter in POST and as part of URL in PUT and PATCH.

Create a fundraiser

# Fundraiser with organization beneficiary and one organizer
curl "https://api.pledge.to/v1/fundraisers" \
  -X POST \
  -H "Authorization: Bearer {api_key}" \
  -F "id=9IEgDGbG9gMAEgFoKSvSpg" \
  -F "start_time=2019-05-04 03:00:00 UTC" \
  -F "end_time=2019-05-04 05:00:00 UTC" \
  -F "goal=1500.0" \
  -F "beneficiary[type]=Organization" \
  -F "beneficiary[id]=3685b542-61d5-45da-9580-162dca725966" \
  -F "organizers[][id]=okn6IpWQSNof_JWCMarFSw" \
  -F "organizers[][email]=sam@pledge.to" \
  -F "organizers[][first_name]=Sam" \
  -F "organizers[][last_name]=Goldstein"

# Fundraiser with crowdfunding beneficiary and multiple organizers
curl "https://api.pledge.to/v1/fundraisers" \
  -X POST \
  -H "Authorization: Bearer {api_key}" \
  -F "id=7FEYuvnaeCTgQ8TuJkDsRQ" \
  -F "start_time=2019-05-05 00:00:00 UTC" \
  -F "end_time=2019-05-10 00:00:00 UTC" \
  -F "goal=3000.0" \
  -F "beneficiary[type]=Crowdfund" \
  -F "beneficiary[purpose]=Trip to Sweden" \
  -F "organizers[][id]=s660Z0wmdarLGgqp85oSdg" \
  -F "organizers[][email]=steve@pledge.to" \
  -F "organizers[][first_name]=Steve" \
  -F "organizers[][last_name]=Mansley" \
  -F "organizers[][id]=lwkV8LnEY9QMsprRI56BKw" \
  -F "organizers[][email]=margie@pledge.to" \
  -F "organizers[][first_name]=Margarette" \
  -F "organizers[][last_name]=Stewerdson"

# Fundraiser with organization beneficiary and one organizer
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.post(
  "https://api.pledge.to/v1/fundraisers",
  {
    id: "9IEgDGbG9gMAEgFoKSvSpg",
    start_time: "2019-05-04 03:00:00 UTC",
    end_time: "2019-05-04 05:00:00 UTC",
    goal: "1500.0",
    beneficiary: {
      type: "Organization",
      id: "3685b542-61d5-45da-9580-162dca725966"
    },
    organizers: [
      {
        id: "okn6IpWQSNof_JWCMarFSw",
        email: "sam@pledge.to",
        first_name: "Sam",
        last_name: "Goldstein"
      }
    ]
  },
  headers
)

# Fundraiser with crowdfunding beneficiary and multiple organizers
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.post(
  "https://api.pledge.to/v1/fundraisers",
  {
    id: "7FEYuvnaeCTgQ8TuJkDsRQ",
    start_time: "2019-05-05 00:00:00 UTC",
    end_time: "2019-05-10 00:00:00 UTC",
    goal: "3000.0",
    beneficiary: {
      type: "Crowdfund",
      purpose: "Trip to Sweden"
    },
    organizers: [
      {
        id: "s660Z0wmdarLGgqp85oSdg",
        email: "steve@pledge.to",
        first_name: "Steve",
        last_name: "Mansley"
      },
      {
        id: "lwkV8LnEY9QMsprRI56BKw",
        email: "margie@pledge.to",
        first_name: "Margarette",
        last_name: "Stewerdson"
      }
    ]
  },
  headers
)

# Fundraiser with organization beneficiary and one organizer
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.post(
  "https://api.pledge.to/v1/fundraisers",
  data={
    "id": "9IEgDGbG9gMAEgFoKSvSpg",
    "start_time": "2019-05-04 03:00:00 UTC",
    "end_time": "2019-05-04 05:00:00 UTC",
    "goal": "1500.0",
    "beneficiary": {
      "type": "Organization",
      "id": "3685b542-61d5-45da-9580-162dca725966"
      },
    "organizers": [
      {
        "id": "okn6IpWQSNof_JWCMarFSw",
        "email": "sam@pledge.to",
        "first_name": "Sam",
        "last_name": "Goldstein"
        }
      ]
    },
  headers=headers
  )

# Fundraiser with crowdfunding beneficiary and multiple organizers
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.post(
  "https://api.pledge.to/v1/fundraisers",
  data={
    "id": "7FEYuvnaeCTgQ8TuJkDsRQ",
    "start_time": "2019-05-05 00:00:00 UTC",
    "end_time": "2019-05-10 00:00:00 UTC",
    "goal": "3000.0",
    "beneficiary": {
      "type": "Crowdfund",
      "purpose": "Trip to Sweden"
      },
    "organizers": [
      {
        "id": "s660Z0wmdarLGgqp85oSdg",
        "email": "steve@pledge.to",
        "first_name": "Steve",
        "last_name": "Mansley"
        },
      {
        "id": "lwkV8LnEY9QMsprRI56BKw",
        "email": "margie@pledge.to",
        "first_name": "Margarette",
        "last_name": "Stewerdson"
        }
      ]
    },
  headers=headers
  )

Example response (organization; single organizer)

{
  "id": "",
  "start_time": "2019-05-04 03:00:00 UTC",
  "end_time": "2019-05-04 05:00:00 UTC",
  "goal": "1500.0",
  "total_raised": "128.22",
  "total_donors": "7",
  "beneficiary": {
    "type": "Organization",
    "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",
    "causes": [
      {
        "id": 73,
        "name": "Disaster Relief",
        "parent_id": null
      },
      {
        "id": 91,
        "name": "Society",
        "parent_id": null
      }
    ],
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/organizations/53-0196605/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",
    "disbursement_type": "standard"
    "impact_metrics": [],
    "sustainable_development_goals": [
      {
        "id": 3,
        "name": "good health and well-being"
      },
      {
        "id": 10,
        "name": "reduced inequalities"
      },
      {
        "id": 15,
        "name": "life on land"
      },
      {
        "id": 16,
        "name": "peace, justice and strong institutions"
      },
      {
        "id": 17,
        "name": "partnerships for the goals"
      }
    ],
  },
  "organizers": [
    {
      "id": "okn6IpWQSNof_JWCMarFSw",
      "email": "sam@pledge.to",
      "first_name": "Sam",
      "last_name": "Goldstein"
    }
  ],
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Example response (crowdfund; multiple organizers)

{
  "id": "",
  "start_time": "2019-05-05 00:00:00 UTC",
  "end_time": "2019-05-10 00:00:00 UTC",
  "goal": "3000.0",
  "total_raised": "587.01",
  "total_donors": "20",
  "beneficiary": {
    "type": "Crowdfund",
    "purpose": "Trip to Sweden"
  },
  "organizers": [
    {
      "id": "s660Z0wmdarLGgqp85oSdg",
      "email": "steve@pledge.to",
      "first_name": "Steve",
      "last_name": "Mansley"
    },
    {
      "id": "lwkV8LnEY9QMsprRI56BKw",
      "email": "margie@pledge.to",
      "first_name": "Margarette",
      "last_name": "Stewerdson"
    }
  ],
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Create a fundraiser for a non-profit organization or personal crowdfunding campaign.

HTTP request

POST https://api.pledge.to/v1/fundraisers

Parameters

Parameter	Description
id String Optional	Unique idendifier for fundraiser. Will be auto-generated if not specified.
start_time Datetime String Optional	Date and time event starts, if relevant.
end_time Datetime String Optional	Date and time event ends, if relevant.
goal Decimal Optional	Amount you want to raise for this fundraiser.
beneficiary[type] String	Type of beneficiary. `'Organization'` or `'Crowdfund'`.
beneficiary[id] String	Non-profit organization’s unique identifier. Only when `beneficiary[type]` is `'Organization'`
beneficiary[purpose] String	Name of crowdfunding campaign. Only when `beneficiary[type]` is `'Crowdfund'`
organizers[][id] String Optional	Unique identifier for organizer user.
organizers[][email] String Optional	Organizer user’s email address.
organizers[][first_name] String Optional	Organizer user’s first name.
organizers[][last_name] String Optional	Organizer user’s last name.
user_ip_address String Optional	The IP address from which the TOS was accepted by the organizer user. Only when `beneficiary[type]` is `'Crowdfund'`
user_agent String Optional	The user agent of the browser from which the TOS was accepted by the organizer user. Only when `beneficiary[type]` is `'Crowdfund'`

Update a fundraiser

curl "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg" \
  -X PATCH \
  -H "Authorization: Bearer {api_key}" \
  -F "goal=3000.0"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.patch(
  "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg",
  {
    goal: "3000.0"
  },
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.patch(
  "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg",
  data={
    "goal": "3000.0"
    },
  headers=headers
  )

Example response

{
  "id": "",
  "start_time": "2019-05-04 03:00:00 UTC",
  "end_time": "2019-05-04 05:00:00 UTC",
  "goal": "3000.0",
  "total_raised": "128.22",
  "total_donors": "7",
  "beneficiary": {
    "type": "Organization",
    "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",
    "causes": [
      {
        "id": 73,
        "name": "Disaster Relief",
        "parent_id": null
      },
      {
        "id": 91,
        "name": "Society",
        "parent_id": null
      }
    ],
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/organizations/53-0196605/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",
    "disbursement_type": "standard"
    "impact_metrics": [],
    "sustainable_development_goals": [
      {
        "id": 3,
        "name": "good health and well-being"
      },
      {
        "id": 10,
        "name": "reduced inequalities"
      },
      {
        "id": 15,
        "name": "life on land"
      },
      {
        "id": 16,
        "name": "peace, justice and strong institutions"
      },
      {
        "id": 17,
        "name": "partnerships for the goals"
      }
    ],
  },
  "organizers": [
    {
      "id": "okn6IpWQSNof_JWCMarFSw",
      "email": "sam@pledge.to",
      "first_name": "Sam",
      "last_name": "Goldstein"
    }
  ],
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Update a fundraiser.

HTTP request

PATCH https://api.pledge.to/v1/fundraisers/{id}

Parameters

Same as create except for id. Partial parameters are allowed.

Place a fundraiser

curl "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg" \
  -X PUT \
  -H "Authorization: Bearer {api_key}" \
  -F "start_time=2019-05-04 03:00:00 UTC" \
  -F "end_time=2019-05-04 05:00:00 UTC" \
  -F "goal=1500.0" \
  -F "beneficiary[type]=Organization" \
  -F "beneficiary[id]=3685b542-61d5-45da-9580-162dca725966" \
  -F "organizers[][id]=s660Z0wmdarLGgqp85oSdg" \
  -F "organizers[][email]=steve@pledge.to" \
  -F "organizers[][first_name]=Steve" \
  -F "organizers[][last_name]=Mansley" \
  -F "organizers[][id]=lwkV8LnEY9QMsprRI56BKw" \
  -F "organizers[][email]=margie@pledge.to" \
  -F "organizers[][first_name]=Margarette" \
  -F "organizers[][last_name]=Stewerdson"

# Fundraiser with organization beneficiary and one organizer
require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.put(
  "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg",
  {
    start_time: "2019-05-04 03:00:00 UTC",
    end_time: "2019-05-04 05:00:00 UTC",
    goal: "1500.0",
    beneficiary: {
      type: "Organization",
      id: "3685b542-61d5-45da-9580-162dca725966"
    },
    organizers: [
      {
        id: "s660Z0wmdarLGgqp85oSdg",
        email: "steve@pledge.to",
        first_name: "Steve",
        last_name: "Mansley"
      },
      {
        id: "lwkV8LnEY9QMsprRI56BKw",
        email: "margie@pledge.to",
        first_name: "Margarette",
        last_name: "Stewerdson"
      }
    ]
  },
  headers
)

# Fundraiser with organization beneficiary and one organizer
import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.put(
  "https://api.pledge.to/v1/fundraisers/9IEgDGbG9gMAEgFoKSvSpg",
  data={
    "start_time": "2019-05-04 03:00:00 UTC",
    "end_time": "2019-05-04 05:00:00 UTC",
    "goal": "1500.0",
    "beneficiary": {
      "type": "Organization",
      "id": "3685b542-61d5-45da-9580-162dca725966"
      },
    "organizers": [
      {
        "id": "s660Z0wmdarLGgqp85oSdg",
        "email": "steve@pledge.to",
        "first_name": "Steve",
        "last_name": "Mansley"
        },
      {
        "id": "lwkV8LnEY9QMsprRI56BKw",
        "email": "margie@pledge.to",
        "first_name": "Margarette",
        "last_name": "Stewerdson"
        }
      ]
    },
  headers=headers
  )

Example response

{
  "id": "",
  "start_time": "2019-05-04 03:00:00 UTC",
  "end_time": "2019-05-04 05:00:00 UTC",
  "goal": "1500.0",
  "total_raised": "128.22",
  "total_donors": "7",
  "beneficiary": {
    "type": "Organization",
    "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",
    "causes": [
      {
        "id": 73,
        "name": "Disaster Relief",
        "parent_id": null
      },
      {
        "id": 91,
        "name": "Society",
        "parent_id": null
      }
    ],
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/organizations/53-0196605/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",
    "disbursement_type": "standard"
    "impact_metrics": [],
    "sustainable_development_goals": [
      {
        "id": 3,
        "name": "good health and well-being"
      },
      {
        "id": 10,
        "name": "reduced inequalities"
      },
      {
        "id": 15,
        "name": "life on land"
      },
      {
        "id": 16,
        "name": "peace, justice and strong institutions"
      },
      {
        "id": 17,
        "name": "partnerships for the goals"
      }
    ],
  },
  "organizers": [
    {
      "id": "s660Z0wmdarLGgqp85oSdg",
      "email": "steve@pledge.to",
      "first_name": "Steve",
      "last_name": "Mansley"
    },
    {
      "id": "lwkV8LnEY9QMsprRI56BKw",
      "email": "margie@pledge.to",
      "first_name": "Margarette",
      "last_name": "Stewerdson"
    }
  ],
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Create or replace a fundraiser.

HTTP request

PUT https://api.pledge.to/v1/fundraisers/{id}

Parameters

Same as create except for id. Full parameters must be specified.

Embedding fundraiser widgets

You can embed donation widgets and/or nonprofit search widgets associated with your fundraisers on your website.

Impact calculators

The impact calculator API allows you to manage your impact calculators. An impact calculator is a real-time donation tracker that can be embedded onto a website to show your impact. Visit our Give & Grow page to see a demo.

Impact calculator resource

Example impact calculator response

{
  "id": "AU9puRFzeJbU_EdMLoqwsA",
  "name": "Default calculator",
  "icon": "environment",
  "brand_color": "#443a4a",
  "widget_style": "brand_color_in_background",
  "currency_symbol": "$",
  "external_id": "nil",
  "organization_ids": [],
  "formula": "organization_amount",
  "description": "raised for 1% For The Planet",
  "info": "$1 per product sold will be donated to 1% For The Planet with no caps or end dates.",
  "amount": 727,
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Attribute	Description
id String	Unique identifier. Used in widget embed.
name String	Name of impact calculator.
icon String	Icon that appears in the impact calculator. Possible values: •`food` •`animals` •`arts` •`clean-energy` •`clean-water` •`natural-disaster` •`disease-medicine` •`dress` •`economic-growth` •`education` •`employment` •`environment` •`gender-equality` •`gift` •`health` •`housing` •`human-rights` •`lgbtqia` •`philanthropy` •`spirituality` •`ribbon` •`veterans` •`other`
color String	Primary color for the impact calculator.
style String	Color style. Possible values: •`background` •`foreground`
currency_symbol String	Currency symbol for showing amount raised.
external_id String	Filters your amount raised based on the external_id associated with your donations.
organization_ids Array	Array of organization IDs to filter your amount raised based on organizations donated to.
formula String	A formula that describes how to compute the amount displayed in the impact calculator. Possible values: •`organization_amount` •`external_id`
description String	Text that appears after the amount.
info String	Text that appears when the info button is clicked
amount Integer	Impact or dollar amount tracked by the impact calculator
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 impact calculators

curl "https://api.pledge.to/v1/impact_calculators" \
  -H "Authorization: Bearer {api_key}"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledge.to/v1/impact_calculators",
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledge.to/v1/impact_calculators",
  headers=headers
  )

Example response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledge.to/v1/impact_calculators",
  "next": null,
  "previous": null,
  "total_count": 2,
  "results": [
    {
      "id": "AU9puRFzeJbU_EdMLoqwsA",
      "name": "Default calculator",
      "icon": "environment",
      "brand_color": "#443a4a",
      "widget_style": "brand_color_in_background",
      "currency_symbol": "$",
      "external_id": "nil",
      "organization_ids": [],
      "formula": "organization_amount",
      "description": "raised for 1% For The Planet",
      "info": "$1 per product sold will be donated to 1% For The Planet with no caps or end dates.",
      "amount": 727,
      "created_at": "2016-01-01T12:00:00Z",
      "updated_at": "2016-01-01T12:00:00Z"
    },
    {
      "id": "3sd3uRFzeJbU_EdMLoqwsA",
      "name": "Clean Water",
      "icon": "clean-water",
      "brand_color": "#443a4a",
      "widget_style": "brand_color_in_background",
      "currency_symbol": "",
      "external_id": "nil",
      "organization_ids": ["f570f929-f9f1-4ff1-a1ac-a250be1fd491"],
      "formula": "organization_amount",
      "description": "people provided with clean drinking water for one year",
      "info": "5% per product sold will be donated to water.org no caps or end dates.",
      "amount": 230,
      "created_at": "2016-01-01T12:00:00Z",
      "updated_at": "2016-01-01T12:00:00Z"
    }
  ]
}

List of all impact calculators.

HTTP request

GET https://api.pledge.to/v1/impact_calculators

Parameters

Parameter	Description
page Integer Optional	Page number.
per_page Integer Optional	Specifies the number of results returned per page. Max 100.

Retrieve impact calculator details

curl "https://api.pledge.to/v1/impact_calculators/" \
  -H "Authorization: Bearer {api_key}"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledge.to/v1/impact_calculators/",
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledge.to/v1/impact_calculators/",
  headers=headers
  )

Example response

{
  "id": "AU9puRFzeJbU_EdMLoqwsA",
  "name": "Default calculator",
  "icon": "environment",
  "brand_color": "#443a4a",
  "widget_style": "brand_color_in_background",
  "currency_symbol": "$",
  "external_id": "nil",
  "organization_ids": [],
  "formula": "organization_amount",
  "description": "raised for 1% For The Planet",
  "info": "$1 per product sold will be donated to 1% For The Planet with no caps or end dates.",
  "amount": 727,
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Retrieve details of an impact calculator.

HTTP request

GET https://api.pledge.to/v1/impact_calculators/{id}

Create an Impact Calculator

curl "https://api.pledge.to/v1/impact_calculators" \
  -X POST \
  -H "Authorization: Bearer {api_key}" \
  -F "icon=clean-water"
  -F "color="
  -F "style="
  -F "currency_symbol="
  -F "external_id=nil"
  -F "formula=organization_amount"
  -F "description=people provided with clean drinking water for one year"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.post(
  "https://api.pledge.to/v1/impact_calculators",
  {
    icon: "clean-water",
    color: "",
    style: "",
    currency_symbol: "",
    external_id: "nil",
    formula: "organization_amount",
    description: "people provided with clean drinking water for one year",
  },
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.post(
  "https://api.pledge.to/v1/impact_calculators",
  data={
    "icon": "clean-water",
    "color": "",
    "style": "",
    "currency_symbol": "",
    "external_id": "nil",
    "formula": "organization_amount",
    "description": "people provided with clean drinking water for one year",
    },
  headers=headers
  )

Example response

{
  "id": "3sd3uRFzeJbU_EdMLoqwsA",
  "name": "Clean Water",
  "icon": "clean-water",
  "brand_color": "#443a4a",
  "widget_style": "brand_color_in_background",
  "currency_symbol": "",
  "external_id": "nil",
  "organization_ids": ["f570f929-f9f1-4ff1-a1ac-a250be1fd491"],
  "formula": "organization_amount",
  "description": "people provided with clean drinking water for one year",
  "info": "5% per product sold will be donated to water.org no caps or end dates.",
  "amount": 230,
  "created_at": "2016-01-01T12:00:00Z",
  "updated_at": "2016-01-01T12:00:00Z"
}

Create an impact calculator.

HTTP request

POST https://api.pledge.to/v1/impact_calculators

Parameters

Parameter	Description
name String	Name of impact calculator.
icon String	Icon that appears in the impact calculator.
color String	Primary color for the impact calculator.
style String	Color style.
currency_symbol String Optional	Currency symbol for showing amount raised.
external_id String Optional	Filters your amount raised based on the external_id associated with your donations.
organization_ids Array Optional	Array of organization IDs to filter your amount raised based on organizations donated to.
formula String	A formula that describes how to compute the amount displayed in the impact calculator. If you are showing amount raised with a currency, you will most likely set this value to `organization_amount` or `external_id`. If you want to show an impact metric, such as number of gallons of clean water provided, you can use basic mathematical operations in the formula. Sample value: `organization_amount / 4` If you know that it costs $0.25 to provide a gallon of clean water, this formula will calculate the number of gallons of water provided.
description String	Text that appears after the amount.
info String	Text that appears when the info button is clicked

Update an impact calculator

curl "https://api.pledge.to/v1/impact_calculators/AU9puRFzeJbU_EdMLoqwsA" \
  -X PATCH \
  -H "Authorization: Bearer {api_key}" \
  -F "icon=clean-water"
  -F "color=#443a4a"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.patch(
  "https://api.pledge.to/v1/impact_calculators/AU9puRFzeJbU_EdMLoqwsA",
  {
    icon: "clean-water",
    color: "#443a4a"
  },
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.patch(
  "https://api.pledge.to/v1/impact_calculators/AU9puRFzeJbU_EdMLoqwsA",
  data={
    "icon": "clean-water",
    "color": "#443a4a"
    },
  headers=headers
  )

Update an impact calculator. Method PATCH allows for a partial update of the object.

HTTP request

PATCH https://api.pledge.to/v1/impact_calculators

Parameters

Same as create.

Embed an impact calculator

You can embed impact calculator widgets associated with your impact calculator resources on your website.

Organizations

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

Organization resource

Example organization resource

{
  "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",
  "causes": [
    {
      "id": 77,
      "name": "Climate Change",
      "parent_id": 76
    },
    {
      "id": 76,
      "name": "Environment",
      "parent_id": null
    },
    {
      "id": 59,
      "name": "Education",
      "parent_id": null
    }
  ],
  "website_url": "http://www.surfrider.org/",
  "profile_url": "https://www.pledge.to/organizations/95-3941826/surfrider-foundation",
  "logo_url": "https://res.cloudinary.com/pledgeling/w_266%2Ch_266%2Cc_fit/prod-media/images%2Fnpos%2Flogos%2Fbatched%2F718.jpg",
  "disbursement_type": "standard"
  "impact_metrics": [
    {
      "amount": 500,
      "currency": "usd",
      "description": "$500 educates 2,000 school children about recycling and keeping our waters clean"
    },
    {
      "amount": 250,
      "currency": "usd",
      "description": "$250 removes 1,000 pounds of trash from the beach by providing bags and gloves"
    }
  ],
  "sustainable_development_goals": [
    {
      "id": 6,
      "name": "clean water and sanitation"
    },
    {
      "id": 7,
      "name": "affordable and clean energy"
    }
  ],
}

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.
causes Object Array	Collection of the organization's causes. Each object contains: •`id` •`name` •`parent_id` (if applicable) See a full list of causes. Note: `causes.id` can change and should only be used to establish a hierarchy of parent and child causes for the given payload.
website_url String	Website URL.
profile_url String	Pledge profile URL.
logo_url String	Logo URL.
disbursement_type String	Disbursement type. Possible values: •`standard` •`international_1` •`international_2`
impact_metrics Object Array	Collection of the organization's impact metrics. Each object contains: •`amount` •`currency` •`description`
sustainable_development_goals Object Array	Collection of the organization's sustainable development goals. Each object contains: •`id` •`name`

List all organizations

curl "https://api.pledge.to/v1/organizations" \
  -H "Authorization: Bearer {api_key}"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.get(
  "https://api.pledge.to/v1/organizations",
  headers
)

import requests

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

Example response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledge.to/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.pledge.to/organizations/53-0196605/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",
      "disbursement_type": "standard"
    },
    {
      "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.pledge.to/organizations/95-3941826/surfrider-foundation",
      "logo_url": "https://res.cloudinary.com/pledgeling/w_266%2Ch_266%2Cc_fit/prod-media/images%2Fnpos%2Flogos%2Fbatched%2F718.jpg",
      "disbursement_type": "standard"
    }
  ]
}

List of all organizations.

HTTP request

GET https://api.pledge.to/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. See a full 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.
per_page Integer Optional	Specifies the number of results returned per page. Max 100.

Retrieve organization details

curl "https://api.pledge.to/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.pledge.to/v1/organizations/3685b542-61d5-45da-9580-162dca725966",
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.get(
  "https://api.pledge.to/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",
  "causes": [
    {
      "id": 73,
      "name": "Disaster Relief",
      "parent_id": null
    },
    {
      "id": 91,
      "name": "Society",
      "parent_id": null
    }
  ],
  "website_url": "http://www.redcross.org/",
  "profile_url": "https://www.pledge.to/organizations/53-0196605/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",
  "disbursement_type": "standard"
  "impact_metrics": [],
  "sustainable_development_goals": [
    {
      "id": 3,
      "name": "good health and well-being"
    },
    {
      "id": 10,
      "name": "reduced inequalities"
    },
    {
      "id": 15,
      "name": "life on land"
    },
    {
      "id": 16,
      "name": "peace, justice and strong institutions"
    },
    {
      "id": 17,
      "name": "partnerships for the goals"
    }
  ],
}

Retrieve details of an organization.

HTTP request

GET https://api.pledge.to/v1/organizations/{id}

Request an organization

curl "https://api.pledge.to/v1/organizations" \
  -X POST \
  -H "Authorization: Bearer {api_key}" \
  -F "ngo_id=58-2060131"

require "rest-client"

headers = { Authorization: "Bearer {api_key}" }
response = RestClient.post(
  "https://api.pledge.to/v1/organizations",
  {
    ngo_id: "58-2060131",
  },
  headers
)

import requests

headers = { "Authorization": "Bearer {api_key}" }
r = requests.post(
  "https://api.pledge.to/v1/organizations",
  data={
    "ngo_id": "58-2060131",
    },
  headers=headers
  )

Successful response has a 202 Accepted status and empty body

Unsuccessful response example

{
  "message": [ "Please enter a valid EIN" ],
  "error_codes": [ "ngo_id_invalid" ]
}

Request an organization to be added to Pledge’s network.

HTTP request

POST https://api.pledge.to/v1/organizations

Parameters

Parameter	Description
ngo_id String	NGO ID (such as EIN for US based non-profits) of the organization you wish added to our database.

Possible errors

Error code	Message	Meaning
ngo_id_invalid	Please enter a valid EIN	The NGO ID entered was malformed or missing
ngo_exists	The nonprofit you requested already exists	The nonprofit requested is already in our database and is public
ngo_in_process	The nonprofit you requested is in the process of being added to the Pledge network	The nonprofit has already been requested by the partner and is in review
ngo_ineligible	The organization you requested is not eligible	The organization is not eligible according to the partner’s rules

Webhooks

Optionally, webhook URLs can be configured through the API. To configure the webhook URLs through the interface, visit the Impact Hub.

List all webhook URLs

curl "https://api.pledge.to/v1/webhooks" \
  -X GET \
  -H "Authorization: Bearer {api_key}"

Example response

{
  "page": 1,
  "per": 25,
  "uri": "https://api.pledge.to/v1/webhooks",
  "next": null,
  "previous": null,
  "total_count": 2,
  "results":
  [
    {
      "id": "8111970d-4047-4a45-b552-fbd7c7af922c",
      "url":"https://www.yourwebsite.com/webhook"
    },
    {
      "id": "145a004b-8d17-4684-a9d6-69a2da50c3e4",
      "url": "https://www.anothersite.com/endpoint"
    }  
  ]
}

List all webhook URLs.

HTTP request

GET https://api.pledge.to/v1/webhooks

Parameters

Parameter	Description
page Integer Optional	Page number.

Retrieve a webhook URL

curl "https://api.pledge.to/v1/webhooks/8111970d-4047-4a45-b552-fbd7c7af922c" \
  -X GET \
  -H "Authorization: Bearer {api_key}"

Example response

{
  "id": "8111970d-4047-4a45-b552-fbd7c7af922c",
  "url":"https://www.yourwebsite.com/webhook"
}

Retrieve a webhook URL.

HTTP request

GET https://api.pledge.to/v1/webhooks/{id}

Add a webhook URL

curl "https://api.pledge.to/v1/webhooks" \
  -X POST \
  -H "Authorization: Bearer {api_key}" \
  -F "url=https://www.yourwebsite.com/webhook"

Example response

{
  "id": "8111970d-4047-4a45-b552-fbd7c7af922c",
  "url":"https://www.yourwebsite.com/webhook"
}

Add a webhook URL.

HTTP request

POST https://api.pledge.to/v1/webhooks

Parameters

Parameter	Description
url String	Webhook URL to be added to receive webhooks from Pledge.

Update a webhook URL

curl "https://api.pledge.to/v1/webhooks/8111970d-4047-4a45-b552-fbd7c7af922c" \
  -X PATCH \
  -H "Authorization: Bearer {api_key}" \
  -F "url=https://www.yourwebsite.com/webhook"

Example response

{
  "id": "8111970d-4047-4a45-b552-fbd7c7af922c",
  "url":"https://www.yourwebsite.com/webhook"
}

Update a webhook URL.

HTTP request

PATCH https://api.pledge.to/v1/webhooks/{id}

Parameters

Parameter	Description
url String	Webhook URL to be added to receive webhooks from Pledge.

Remove a webhook URL

curl "https://api.pledge.to/v1/webhooks/8111970d-4047-4a45-b552-fbd7c7af922c" \
  -X DELETE \
  -H "Authorization: Bearer {api_key}"

Example response

{
  "id": "8111970d-4047-4a45-b552-fbd7c7af922c",
  "deleted": true
}

Remove a webhook URL.

HTTP request

DELETE https://api.pledge.to/v1/webhooks/{id}

Widgets

Widget loader script

<script src="https://www.pledge.to/assets/widget.js" id="plg-widget" async></script>

Pledge offers several embeddable widgets that you can place on your website. All widgets require the use of our widget loader script along with an embed code placed where you would the widget to appear. This embed code can contain options to customize your widget.

Embed code using widget ID

<div class="plg-donate" data-widget-id="wGm2sf4YjKrB4568xNaoKA"></div>

Embed code using partner key and item ID

<div class="plg-donate"
  data-partner-key="1c664ffa32752a5dd9cde6a339d4498a"
  data-item-id="9IEgDGbG9gMAEgFoKSvSpg"
></div>

Embed code with user info pre-filled

<div class="plg-donate"
  data-widget-id="wGm2sf4YjKrB4568xNaoKA"
  data-first-name="Michael"
  data-last-name="Sanders"
  data-email="m.sanders@mail.com"
></div>

Embed code with style customizations

<div class="plg-donate"
  data-widget-id="wGm2sf4YjKrB4568xNaoKA"
  data-style-transparent="true"
  data-style-brand-color="#fd1100"
></div>

Embed code in a non-US locale and currency

<div class="plg-donate"
  data-widget-id="wGm2sf4YjKrB4568xNaoKA"
  data-locale="nb-NO"
  data-currency="NOK"
></div>

Pledge donation widgets are donation forms that can be embedded into a website, or as a standalone web page. The donation forms have a responsive design that makes them well suited for both desktop and mobile layouts. Each widget has a unique embed code that supports the following parameters.

Parameters

Parameter	Description
data-partner-key String	Your unique partner key. Provided in your developer dashboard, or via your account manager.
data-widget-id String Must use one	A unique ID for the donation form. This is used primarily when the donation widget was created in the Impact Hub.
data-ein String Must use one	The EIN of the nonprofit. Typically used when to dynamically generate the donation. Can be used in conjunction with the Pledge nonprofit search API to locate the EIN value.
data-item-id String Must use one	Fundraiser ID, generated by the fundraiser API.
data-amount Number	Set the donation amount.
data-first-name String	Set the first name in the donation form.
data-last-name String	Set the last name in the donation form.
data-email String	Set the email address in the donation form.
data-locale String	Set the locale to render the donation form in different languages.
data-currency String	Set the default currency.
data-style-transparent Boolean	Set when you want the widget to appear with a transparent background.
data-style-dark-bg Boolean	Set when the widget is on a dark background.
data-style-brand-color String	Hex color value. Sets the main color of the widget.
data-style-hide-social Boolean	Hide social share option on the “thank you” screen after the donation is made.
data-template String	Set to template name to load the appropriate configuration.

Donation completed message

Tipping widget postMessage payload

{
  "message": "DonateCompleted",
  "data": {
    "amount": 20.0,
    "tip": 3,
    "total": 23.0
  }
}

Cover costs widget postMessage payload

{
  "message": "DonateCompleted",
  "data": {
    "amount": 20.0,
    "fees": 1.93,
    "total": 21.93
  }
}

When a donation is made it triggers events (via postMessage) that your application can react to. The format for the postMessage payload is a stringified JSON object specifying the associated data. Our donation widgets come in two variations, “Tipping” and “Cover costs”. Each one has a slightly different postMessage payload. Alternatively, if you have a webhook URL configured, you will be notified of donations that way. See our webhook documentation for more information.

Consuming message

Example code consuming postMessage format

const handleDonateCompleted = data => {
  alert('$' + data.total + ' donated!')
}

const handleMessage = e => {
  if (e.origin != 'https://www.pledge.to') return
  const data = JSON.parse(e.data)
  switch (data.message) {
    case 'DonateCompleted':
      return handleDonateCompleted(data.data)
  }
}

addEventListener('message', handleMessage)

In order to make use of the postMessage format, parse the string into a JSON object and then process it according to the message and associated data.

Embed code

<div class="plg-search" data-partner-id="1c664ffa32752a5dd9cde6a339d4498a"></div>

Embed code with goal and organization pre-filled

<div class="plg-search"
  data-partner-id="1c664ffa32752a5dd9cde6a339d4498a"
  data-beneficiary-uuid="3685b542-61d5-45da-9580-162dca725966"
  data-goal="10000"
></div>

The Pledge nonprofit search widget can be embedded into a website to enable your users to easily search Pledge’s nonprofit database. Each widget has a unique embed code that supports the following parameters.

Parameters

Parameter	Description
data-partner-key String Required	Your unique partner key. Provided in your developer dashboard, or via your account manager.
data-item-id String	Renders widget in “selected” mode. Used in conjunction with the fundraiser API. If you pass a fundraiser ID, the widget will auto-load the corresponding nonprofit with a “remove” option.
data-beneficiary-uuid String	Renders widget in “selected” mode, with the specified nonprofit selected.
data-goal Number	Can be used in conjunction with data-beneficiary-uuid. Sets the goal amount in selected mode.
data-featured-uuid String	Allows you to highlight or suggest a nonprofit in the search widget. Pass the nonprofit ID to feature.
data-featured-copy String	Copy for the featured nonprofit.
data-featured-paid Boolean	Set to true if the featured nonprofit is a paid sponsor. This will disclose the sponsorship above the featured nonprofit.

Messages

postMessage data format

{
  "action": "actionName", // All actions have an action key
  "data": {               // Select actions have a data key and structure
    "key": "value"
  }
}

When a user interacts with the search widget, it triggers events (via postMessage) that your application can react to. The two main events are updateEvent and removeEvent. The format for the postMessage payload is a stringified JSON object specifying the action and associated data.

updateEvent

updateEvent sample payload

{
  "action": "updateEvent",
  "data": {
    "beneficiary_type": "Organization",
    "beneficiary_uuid": "ec0b21fc-2671-431e-8a81-783b7a9626c9",
    "goal": null
  }
}

This action has a data structure which specifies the beneficiary type and ID, and the goal set.

removeEvent

removeEvent payload

{
  "action": "removeEvent"
}

This action has no data structure attached.

Consuming messages

Example code consuming postMessage format

const updateEvent = data => {
  // Do something with the data
}

const removeEvent = () => {
  // Do what is necessary to remove the event
}

const handleMessage = e => {
  if (e.origin != 'https://www.pledge.to') return

  const message = JSON.parse(e.data)

  switch (message.action) {
    case 'updateEvent':
      return updateEvent(message.data)
    case 'removeEvent':
      return removeEvent()
  }
}

addEventListener('message', handleMessage)

In order to make use of the postMessage format, parse the string into a JSON object and then process it according to the action and associated data.

Embed code

<div class="plg-impact" data-widget-id="YzbzUML0LwYc3ixk28MqFg"></div>

The Pledge impact calculator widget can be embedded into a website to easily show your impact.

Parameters

Parameter	Description
data-widget-id String Required	A unique ID for the impact calculator resource

Webhooks

Pledge sends webhook events that notify your application via a POST request to a URL configured in your account.

Example webhook

{
  "topic": "donation/created",
  "data": {...}
}

Parameters

Parameter	Description
topic String	Description of the webhook event with a `resource/event` format
data Object	Object describing the result of the event or containing the newly created resource

Donations

The format of the data parameter is identical to the donation resource.

Donation created

Example webhook

{
  "topic": "donation/created",
  "data":  {
    "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",
    "external_id": "439087218",
    "metadata": "shopify_id 870203745",
    "created_at": "2016-01-01T12:00:00Z",
    "updated_at": "2016-01-01T12:00:00Z",
    "network_details": {
      "ip_address": "76.95.183.42",
      "city": "Los Angeles",
      "country_code": "US",
      "postal_code": "90066",
      "region_code": "CA"
    }
  }
}

This webhook is sent whenever a donation is made via your account.

Organization requests

Data parameters

Parameter	Description
ngo_id String	NGO ID (such as EIN for US based non-profits) of the organization you wish added to our database.
status String	Status of the organization request. Possible values: • `approved` • `declined`
reason String Optional	Only for declined requests. The reason the request was declined.

Request approved

Example webhook

{
  "topic": "organization_request/approved",
  "data": {
    "ngo_id": "53-0196605",
    "status": "approved"
  }
}

This webhook is sent whenever we approve an organization you have requested.

Request declined

Example webhook

{
  "topic": "organization_request/declined",
  "data": {
    "ngo_id": "58-2060131",
    "status": "declined",
    "reason": "The organization doesn't like technology"
  }
}

This webhook is sent whenever we decline an organization you have requested, along with a reason why we declined to add it.

Verification

Verifying the webhook event

Example webhook verification

# Choose Ruby or Python to view example code

# Compare the computed HMAC digest using your api_key as the key and
# the webhook event's payload as the message

require 'base64'
require 'openssl'
require 'active_support/security_utils'

calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', api_key, data))
ActiveSupport::SecurityUtils.secure_compare(calculated_hmac, pledgeling_header)

# Compare the computed HMAC digest using your api_key as the key and
# the webhook event's payload as the message

import hmac
import hashlib
import base64

digest = hmac.new(api_key, data.encode('utf-8'), hashlib.sha256).digest()
computed_hmac = base64.b64encode(digest)

return hmac.compare_digest(computed_hmac, pledgeling_header.encode('utf-8'))

Pledge sends a header named Pledge-Signature along with the webhook event, which allows you to verify that the webhook event is coming from us.

Pledge generates the signature using a hash-based message authentication code (HMAC) with SHA-256.

To verify that the webhook event is coming from Pledge, compute an HMAC with the SHA256 hash function using your api_key as the key, and the webhook event's payload as the message, and then Base64 encode the result.

Compare the computed signature to the value of the Pledge-Signature header. If they match, then you can be sure that the webhook event came from Pledge.

API Documentation

REST API

Getting started

Authentication

Pagination

Response codes

Donations

Donation resource

List all donations

HTTP request

Parameters

Retrieve donation details

HTTP request

Create a donation

HTTP request

Parameters

Fundraisers

Fundraiser resource

Crowdfund beneficiary resource

Organizer user resource

Retrieve fundraiser details

HTTP request

Creating/updating fundraisers

Create a fundraiser

HTTP request

Parameters

Update a fundraiser

HTTP request

Parameters

Place a fundraiser

HTTP request

Parameters

Embedding fundraiser widgets

Impact calculators

Impact calculator resource

List all impact calculators

HTTP request

Parameters

Retrieve impact calculator details

HTTP request

Create an Impact Calculator

HTTP request

Parameters

Update an impact calculator

HTTP request

Parameters

Embed an impact calculator

Organizations

Organization resource

List all organizations

HTTP request

Parameters

Retrieve organization details

HTTP request

Request an organization

HTTP request

Parameters

Possible errors

Webhooks

List all webhook URLs

HTTP request

Parameters

Retrieve a webhook URL

HTTP request

Add a webhook URL

HTTP request

Parameters

Update a webhook URL

HTTP request

Parameters

Remove a webhook URL

HTTP request

Widgets

Donation widget

Parameters

Donation completed message

Consuming message

Nonprofit search widget

Parameters

Messages