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