You’ll need an API KEY to connect to Donorbox. To create a key, you’ll need to sign up at https://donorbox.org. After you register with Donorbox, click Account in the top navigation, click API & Zapier Integration on the left, and select Enable API & Zapier Integration. After you confirm and add your billing information, select Set new API Key.
Please be aware that the API & Zapier integration costs $17/month.
If you are looking to integrate with Zapier, please follow this guide.
Copy the generated API key to a safe place as this key will only be shown once for security reasons.
Make API calls to Donorbox
Donorbox API uses basic authentication as our authorization method. Use your organization login email as your authorization username and the API Key as your password.
Here is the general format using CURL:
curl -X METHOD --user login@email.com:YOUR_API_KEY https://donorbox.org/{endpoint}
To test our API endpoints directly in a web browser, use the following format:
https://login@email.com:API_KEY_XXX@donorbox.org/{endpoint}
If your browser does not support this basic authentication URL pattern, use the endpoint URL https://donorbox.org/{endpoint} without email & password and provide these credentials on the popup.
This is the Donorbox API endpoints URL with appropriate HTTP method:
{METHOD} https://donorbox.org{endpoint}
Throughout the documentation we will omit the host name, mentioning only the HTTP METHOD and the endpoint e.g. {GET} /api/v1/campaigns.
Donorbox API endpoints
Campaigns
Get information for all your campaigns.
{GET} /api/v1/campaigns
Output:
[
{
"id":1,
"name":"Donorbox New Campaign",
"slug":"donorbox-new-campaign",
"currency":"usd",
"created_at":"2017-10-20T22:30:55.620Z",
"updated_at":"2017-10-20T22:30:55.620Z",
"goal_amt":"10000.0",
"formatted_goal_amount":"$1,0000",
"total_raised":"2000.0",
"formatted_total_raised":"$2000",
"donations_count":66
}
]
Donations
Get all your organization's donations.
{GET} /api/v1/donations
Output (Stripe):
[
{
"campaign": {
"id": 1,
"name": "Donorbox Campaign"
},
"donor": {
"id": 59,
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"email": "johndoeemail@hotmail.com",
"address":"123 6th St.",
"city":"Melbourne",
"state":"FL",
"zip_code": "32904",
"country":"USA",
"employer":null,
"occupation":null
},
"amount": "100.0",
"formatted_amount": "$100",
"converted_amount": "100.0",
"formatted_converted_amount": "$100",
"recurring": false,
"first_recurring_donation": false,
"amount_refunded": "0.0",
"formatted_amount_refunded": "$0",
"stripe_charge_id": "ch_1BF94aBku99FiTp3uJM5mSKw",
"id": 1,
"status": "paid",
"donation_type": "stripe",
"donation_date": "2017-12-21T17:54:13.432Z",
"anonymous_donation": false,
"gift_aid": false,
"designation": "Designed Cause",
"join_mailing_list": false,
"comment": "thanks",
"donating_company": null,
"currency": "USD",
"converted_currency": "USD",
"utm_campaign": "google_ads",
"utm_source": "Adwords",
"utm_medium": "cpc",
"utm_term": "nonprofit fundraising",
"utm_content": "np1",
"processing_fee": 0.59,
"formatted_processing_fee": "$0.59",
"questions": [
{
"question_type": "radiobutton",
"question": "Would you like to volunteer?",
"answer": "Yes"
},
{
"question_type": "text",
"question": "Why are you donating",
"answer": "I would like to help"
},
{
"question_type": "check",
"question": "First/Last Name is correct?",
"answer": true
},
{
"question_type": "dropdown",
"question": "Would you like to showcase your donation",
"answer": "Yes"
}
]
}
]
Output (PayPal):
[
{
"campaign": {
"id": 1,
"name": "Donorbox Campaign"
},
"donor": {
"id": 59,
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"email": "johndoeemail@hotmail.com",
"address":"123 6th St.",
"city":"Melbourne",
"state":"FL",
"zip_code": "32904",
"country":"USA",
"employer":null,
"occupation":null
},
"amount": "100.0",
"formatted_amount": "$100",
"converted_amount": "100.0",
"formatted_converted_amount": "$100",
"recurring": false,
"first_recurring_donation": false,
"amount_refunded": "0.0",
"formatted_amount_refunded": "$0",
"paypal_transaction_id": "RANDOMPAYPALID",
"id": 1,
"status": "paid",
"donation_type": "paypal",
"donation_date": "2017-12-21T17:54:13.432Z",
"anonymous_donation": false,
"gift_aid": false,
"comment": "thanks",
"donating_company": null,
"currency": "USD",
"converted_currency": "USD",
"utm_campaign": "google_ads",
"utm_source": "Adwords",
"utm_medium": "cpc",
"utm_term": "nonprofit fundraising",
"utm_content": "np1",
"processing_fee": 0.59,
"formatted_processing_fee": "$0.59",
"questions": [
{
"question_type": "radiobutton",
"question": "Would you like to volunteer?",
"answer": "Yes"
},
{
"question_type": "text",
"question": "Why are you donating",
"answer": "I would like to help"
},
{
"question_type": "check",
"question": "First/Last Name is correct?",
"answer": true
},
{
"question_type": "dropdown",
"question": "Would you like to showcase your donation",
"answer": "Yes"
}
]
}
]
Plans
Get information for all your plans.
{GET} /api/v1/plans
Output:
[
{
"id": 168,
"campaign": {
"id": 61,
"name": "Save the jungle campaign"
},
"donor": {
"id": 384,
"name": "Bruce Waine",
"first_name": "Bruce",
"last_name": "Waine",
"email": "bruce@email.com",
"phone": "8038984624",
"address": "123 6th St.",
"city":"Melbourne",
"state":"FL",
"zip_code":"32904",
"country": "USA",
"employer": "Waine Industries",
"occupation": "CEO"
},
"type": "monthly",
"amount": "10.0",
"formatted_amount": "$10",
"payment_method": "Stripe",
"started_at": "2018-07-25",
"last_donation_date": "2018-07-25T05:00:00.000Z",
"next_donation_date": "2018-08-25",
"status": "active"
}
]
Donors
Get information for all your donors.
{GET} /api/v1/donors
Output:
[
{
"id":35,
"created_at":"2017-11-20T14:01:35.597Z",
"updated_at":"2017-11-28T21:49:25.127Z",
"first_name":"John",
"last_name":"Doe",
"email":"johndoe@email.com",
"phone":"123456789",
"address":"123 6th St.",
"city":"Melbourne",
"state":"FL",
"zip_code":"32904",
"country":"USA",
"employer":null,
"occupation":null,
"comment":null,
"donations_count":2,
"last_donation_at":"2017-11-28T21:48:51.260Z",
"total":[
{
"currency":"usd",
"value":100.0
}
]
}
]
Filters
Campaign Filters
Use campaign_id parameter to narrow down the result by a specific campaign.
e.g. {GET} /api/v1/campaigns?id=XX
To filter campaigns by campaign name, use:
{GET} /api/v1/campaigns?name=XXXXXXXX
Plan Filters
Use email parameter to filter the plans by a given donor's email address. This filter is valid only for Plans endpoint.
e.g. {GET} /api/v1/plans?email=XXXX
Use date_from and date_to filters to filter plans by started date. The valid date formats include: YYYY-mm-dd YYYY/mm/dd YYYYmmdd dd-mm-YYYY
e.g. {GET} /api/v1/plans?date_from=YYYY-mm-dd&date_to=YYYY-mm-dd
Use campaign_id filter to filter plans by campaign id. This is the Donorbox campaign id.
e.g. {GET} /api/v1/plans?campaign_id=XXXX
Use campaign_name filter to filter plans by campaign name. This is the Donorbox campaign title that you have defined in Donorbox.
e.g. {GET} /api/v1/plans?campaign_name=XXXXXXX
Use donor_id filter to filter plans by Donorbox donor id. This is the Donorbox generated donor id.
e.g. {GET} /api/v1/plans?donor_id=XXXXXXX
Use first_name filter to filter plans by donor's first name.
e.g. {GET} /api/v1/plans?first_name=XXXXXXX
Use last_name filter to filter plans by donor's last name.
e.g. {GET} /api/v1/plans?last_name=XXXXXXX
Use donor_name filter to filter plans by donor's full name. Note this filter would be similar to using the first_name and last_name paramters in conjunction like first_name=XXXX&last_name=YYYYYY
e.g. {GET} /api/v1/plans?last_name=XXXXXXX XXXXX
Donor Filters
Use id filter to filter donors by Donorbox donor id. This is the Donorbox generated donor id.
e.g. {GET} /api/v1/donors?id=XXX
Use first_name filter to filter and get donors by donor's first name.
e.g. {GET} /api/v1/donors?first_name=XXXXXXX
Use last_name filter to filter and get donors by donor's last name.
e.g. {GET} /api/v1/donors?last_name=XXXXXXX
Use donor_name filter to filter donors by donor's full name. Note this filter would be similar to using the first_name and last_name paramters in conjunction like first_name=XXXX&last_name=YYYYYY
e.g. {GET} /api/v1/donors?last_name=XXXXXXX XXXXX
Use email filter to filter and get donors by donor's email.
e.g. {GET} /api/v1/donors?email=XXXXXXX
Donation Filters
Use email filter to filter and get donations by donor's email.
e.g. {GET} /api/v1/donations?email=XXXXXXX
Use date_from and date_to filters to filter donations by started date. The valid date formats include: YYYY-mm-dd YYYY/mm/dd YYYYmmdd dd-mm-YYYY
e.g. {GET} /api/v1/donations?date_from=YYYY-mm-dd&date_to=YYYY-mm-dd
Use campaign_name filter to filter donations by campaign name. This is the Donorbox campaign title that you have defined in Donorbox.
e.g. {GET} /api/v1/donations?campaign_name=XXXXXXX
Use campaign_id filter to filter donations by campaign id. This is the Donorbox campaign id.
e.g. {GET} /api/v1/donations?campaign_id=XXXX
Use id filter to filter donations by Donorbox donation id. This is the Donorbox generated donation id.
e.g. {GET} /api/v1/donations?id=XXX
Use first_name filter to filter and get donations by donor's first name.
e.g. {GET} /api/v1/donations?first_name=XXXXXXX
Use last_name filter to filter and get donations by donor's last name.
e.g. {GET} /api/v1/donations?last_name=XXXXXXX
Use donor_id filter to filter and get donations by donor's id. This is the Donorbox generated donor id
e.g. {GET} /api/v1/donations?donor_id=XXXXXXX
Use amount filter to filter and get donations by donation amounts.
e.g. {GET} /api/v1/donations?amount[usd][min]=XXX&amount[usd][max]=YYYY
Please note that you can use min and max together to fetch donations in a certain range. You can also use min and max params alone if you want to fetch all the donations above or below a certain threshold.
Ordering
All Donorbox API endpoints support ordering. Use order parameter with asc|desc possible values. The default is desc.
e.g {GET} /api/v1/donations?order=asc
Pagination
All Donorbox API endpoints support pagination. Provide page and per_page parameters to split the result accordingly. The default page size (per_page parameter's value) is 50, maximum 100 allowed. If it exceeds the maximum, it will fallback to default.
e.g. {GET} /api/v1/donors?page=2&per_page=18
Combine filters
Of course, you can combine any of the filters described above, taking into account supported endpoints for a specific filter.
e.g. {GET} /api/v1/donations?order=asc&page=3&per_page=20&campaign_id=XX&&amount[usd][max]=YYYY
NOTE: Please note that you can make 60 API requests per minute.
Comments
0 comments
Article is closed for comments.