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.donorbox.Donorbox(email=None, api_key=None)[source]¶

Instantiate Donorbox class.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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