Donorbox

Overview

Donorbox is an online donation platform through which donors can make one-off or recurring donations. This Parsons class provides methods for extracting donors, campaigns, donations, and plans.

The documentation for the underlying Donorbox API can be found here.

Note

To authenticate, go to your account on donorbox.org and select the “API & Zapier Integration” option under Add-ons. Enable the add-on. (Note that currently Donorbox charges to enable this feature.) Once the add-on is enabled, hit the “Set new API key” button and copy the generated key.

Quickstart

To instantiate the Donorbox class, you can either store the Donorbox accont email and API key as environmental variables (DONORBOX_ACCOUNT_EMAIL, DONORBOX_API_KEY) or pass them in as arguments:

from parsons import Donorbox

# First approach: Use API key and account email via environmental variables
donorbox = Donorbox()

# Second approach: Pass API credentials and user email as arguments
donorbox = Donorbox(email='me@myorg.com', api_key='MYAPIKEY')

You can then call various endpoints:

# Get campaigns

campaigns = donorbox.get_campaigns()                                    # get all campaigns
campaigns = donorbox.get_campaigns(name="My campaign")                  # get campaigns by name
campaigns = donorbox.get_campaigns(name="My campaign", order="desc")    # results in descending order

# Get donations

donations = donorbox.get_donations()                                    # get all donations
donations = donorbox.get_donations(date_to="2022-10-22")                # get all donations before date
donations = donorbox.get_donations(campaign_name="My campaign")         # filter donations by campaign

# Get donors

donors = donorbox.get_donors()                                          # get all donors
donors = donorbox.get_donors(email="example@example.org")               # get donors by email
donors = donorbox.get_donors(page=1, per_page=10)                       # use pagination

# Get plans

plans = donorbox.get_plans()                                            # get all plans
plans = donorbox.get_plans(date_from="2022-10-22")                      # get plans started after date

API

class parsons.Donorbox(email=None, api_key=None)[source]

Instantiate Donorbox class.

Args:

donorbox_account_email: str
The email associated with your Donorbox account. Can be passed as argument or set as DONORBOX_ACCOUNT_EMAIL environment variable.

donorbox_api_key: str
The API key generated by Donorbox for your account. Can be passed as argument or set as DONORBOX_API_KEY environment variable.

get_campaigns(**kwargs)[source]

Get information on campaigns.

Args:

id: int or str: Optional. The ID of the campaign to get. If both id and name are omitted, returns all campaigns.
name: str: Optional. The name of the campaign to get. If both id and name are omitted, retunrs all campaigns.
order: str: Optional. Valid values are “asc” and “desc”. If not supplied, order is descending by default.
page: int: Optional. Donorbox supports pagination for larger results. Use the page to track your progress.
per_page: int: Optional. Results per page when using pagination. Default is 50, maximum is 100.

Returns:

Parsons Table

get_donations(**kwargs)[source]

Get information on donations.

Args:

email: str: Optional. Filter’s donations by donor’s email
date_from: str: Optional. Filters donations to those started on or after the provided date.

Valid formats: YYYY-mm-dd YYYY/mm/dd YYYYmmdd dd-mm-YYYY

If an incorrectly formatted date is provided, an error is raised.
date_to: str: Optional. Filters donations to those started before the provided date.

Valid formats: YYYY-mm-dd YYYY/mm/dd YYYYmmdd dd-mm-YYYY

If an incorrectly formatted date is provided, an error is raised.
campaign_name: str: Optional. Filters by the campaign title that you have defined in Donorbox.
campaign_id: int or str: Optional. Filters by Donorbox campaign id.
donation_id: int or str: Optional. Filters by Donorbox donations id.
first_name: str: Optional. Filters by donor’s first name.
last_name: str: Optional. Filters by donor’s last name.
donor_id: int or str: Optional. Filters by Donorbox donor id.
amount_min: int or str: Optional. Gets all donations above the provided minimum.
amount_max: int or str: Optional. Gets all donations below the provided maximum.
order: str: Optional. Valid values are “asc” and “desc”. If not supplied, order is descending by default.
page: int: Optional. Donorbox supports pagination for larger results. Use the page to track your progress.
per_page: int: Optional. Results per page when using pagination. Default is 50, maximum is 100.

Returns:

Parsons Table

get_donors(**kwargs)[source]

Get information on donors.

Args:

donor_id: str or int
Optional. Filters by donor ID.

first_name: str
Optional. Filters by donor’s first name.

last_name: str
Optional. Filters by donor’s last name.

donor_name: str
Optional. Filter by donor’s full name

email: str
Optional. Filter’s donations by donor’s email

order: str
Optional. Valid values are “asc” and “desc”. If not supplied, order is descending by default.

page: int
Optional. Donorbox supports pagination for larger results. Use the page to track your progress.

per_page: int
Optional. Results per page when using pagination. Default is 50, maximum is 100.

Returns:: Parsons Table

get_plans(**kwargs)[source]

Get information on plans.

Args:

email: str
Optional. Filter’s plans by donor’s email address.

date_from: str

Optional. Filters plans to those started on or after the provided date.

Valid formats: YYYY-mm-dd YYYY/mm/dd YYYYmmdd dd-mm-YYYY

If an incorrectly formatted date is provided, an error is raised.

date_to: str

Optional. Filters plans to those started before the provided date.

Valid formats: YYYY-mm-dd YYYY/mm/dd YYYYmmdd dd-mm-YYYY

If an incorrectly formatted date is provided, an error is raised.

campaign_id: int or str
Optional. Filters by Donorbox campaign id.

campaign_name: str
Optional. Filters by the campaign title that you have defined in Donorbox.

donor_id: str or int
Optional. Filters by donor ID.

first_name: str
Optional. Filters by donor’s first name.

last_name: str
Optional. Filters by donor’s last name.

donor_name: str
Optional. Filter by donor’s full name

order: str
Optional. Valid values are “asc” and “desc”. If not supplied, order is descending by default.

page: int
Optional. Donorbox supports pagination for larger results. Use the page to track your progress.

per_page: int
Optional. Results per page when using pagination. Default is 50, maximum is 100.

Returns:: Parsons Table