NAV Navbar
cURL Ruby Python

Developer resources


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

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

Welcome to Pledge’s developer resources!

Pledge’s developer resources 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 API in your platform? Create an account to gain access to Pledge APIs.

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}

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",
      "cover_fees": false,
      "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",
      "cover_fees": true,
      "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",
  "cover_fees": false,
  "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.
cover_fees
Boolean
If true, processing fees are charged to your payment method on file when API donations are processed. If false, processing fees are deducted from the donation during processing.

Default is false
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:
pendingprocessedcanceled
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",
      "cover_fees": false,
      "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",
      "cover_fees": true,
      "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.
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:
pendingprocessedcanceled
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",
  "cover_fees": false,
  "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",
  "cover_fees": false,
  "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.
cover_fees
Boolean
Optional
If true, processing fees are charged to your payment method on file when API donations are processed. If false, processing fees are deducted from the donation during processing.

Default is false
phone_number
String
Optional
User’s phone number.

Sample values:
(918) 555-01889185550188
external_id
String
Optional
An identifier to tag donations for a specific Impact Calculator
metadata
String
Optional
Custom metadata.

Sample values:
Christmas fundraiser donationExternal 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",
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/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",
    "disbursement_type": "standard"
  },
  "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.
category
String
Crowdfunding category.

Possible values:
AnimalsBusinessCommunityCreativeEducationEmergenciesEnvironmentFaithFamilyMedicalMemorialsScienceSportsTravelVolunteerOther
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",
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/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",
    "disbursement_type": "standard"
  },
  "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[category]=Travel" \
  -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",
      category: "Travel",
      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",
      "category": "Travel",
      "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",
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/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",
    "disbursement_type": "standard"
  },
  "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",
    "category": "Travel",
    "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[category]
String
Crowdfunding campaign category. See possible values in crowdfund beneficiary resource.
Only when beneficiary[type] is 'Crowdfund'
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.

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",
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/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",
    "disbursement_type": "standard"
  },
  "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",
    "website_url": "http://www.redcross.org/",
    "profile_url": "https://www.pledge.to/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",
    "disbursement_type": "standard"
  },
  "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:
foodanimalsartsclean-energyclean-waternatural-disasterdisease-medicinedresseconomic-growtheducationemploymentenvironmentgender-equalitygifthealthhousinghuman-rightslgbtqiaphilanthropyspiritualityribbonveteransother
color
String
Primary color for the impact calculator.
style
String
Color style. Possible values:
backgroundforeground
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_amountexternal_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": "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/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",
  "disbursement_type": "standard"
}
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
Pledge profile URL.
logo_url*
String
Logo URL.
disbursement_type
String
Disbursement type. Possible values:
standardinternational_1international_2

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/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",
      "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/718/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. Click here for a 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",
  "website_url": "http://www.redcross.org/",
  "profile_url": "https://www.pledge.to/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",
  "disbursement_type": "standard"
}

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

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",
    "cover_fees": false,
    "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:
approveddeclined
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.

Widgets

Widget loader script

<script src="https://hello.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.

Donation 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
Required
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
Premium feature
Set the locale to render the donation form in different languages.
data-currency
String
Premium feature
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
Premium feature
Set to template name to load the appropriate configuration.
data-relay-donated-event
Boolean
Enables postMessage notification after a donation is made.

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://hello.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.

Nonprofit search widget

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://hello.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.

Impact calculator widget

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