ActBlue

Overview

The ActBlue class allows you to interact with the ActBlue CSV API. Users of this Parsons integration can generate CSVs and manipulate entity CSV data within the Parsons table format.

Note

Authentication

In order to use this class you must generate and use a Client UUID and Client Secret set of credentials. Instructions for generating the set of keys can be found within the CSV API documentation.

Quickstart

To instantiate the ActBlue class, you can either store your ACTBLUE_CLIENT_UUID and ACTBLUE_CLIENT_SECRET keys as environment variables or pass them in as arguments:

from parsons import ActBlue

# First approach: Use API key environment variables

# In bash, set your environment variables like so:
# export ACTBLUE_CLIENT_UUID='MY_UUID'
# export ACTBLUE_CLIENT_SECRET='MY_SECRET'
actblue = ActBlue()

# Second approach: Pass API keys as arguments
actblue = ActBlue(actblue_client_uuid='MY_UUID', actblue_client_secret='MY_SECRET')

You can then make a request to generate a CSV and save its data to a Parsons table using the main helper method, get_contributions():

# Create Parsons table with entity CSV data
parsons_table = actblue.get_contributions(csv_type='paid_contributions', date_range_start='2020-01-01', date_range_end='2020-02-01')

The above example shows how to create a Parsons table with paid contribution data of your entity for the month of January 2020. In addition to ‘paid_contributions’, the other options for csv_type are ‘refunded_contributions’ and ‘managed_form_contributions’.

API

class parsons.actblue.actblue.ActBlue(actblue_client_uuid=None, actblue_client_secret=None, actblue_uri=None, max_retries=None)[source]

Instantiate class.

For instructions on how to generate a Client UUID and Client Secret set, visit https://secure.actblue.com/docs/csv_api#authentication.

Parameters:

  • actblue_client_uuid – str The ActBlue provided Client UUID. Not required if ACTBLUE_CLIENT_UUID env variable set.

  • actblue_client_secret – str The ActBlue provided Client Secret. Not required if ACTBLUE_CLIENT_SECRET env variable set.

  • actblue_uri – str The URI to access the CSV API. Not required, default is https://secure.actblue.com/api/v1. You can set an ACTBLUE_URI env variable or use this URI parameter if a different endpoint is necessary - for example, when running this code in a test environment where you don’t want to hit the actual API.

  • max_retries – int The maximum number of times to poll the API for a download URL. Not required, default is None, which means it will poll indefinitely until a download URL is returned. ACTBLUE_MAX_RETRIES env variable can be set, which will override this parameter.

post_request(csv_type: Literal['paid_contributions', 'refunded_contributions', 'managed_form_contributions'] | None = None, date_range_start: str | None = None, date_range_end: str | None = None) → Response[source]

POST request to ActBlue API to begin generating the CSV.

Parameters:

  • csv_type –

    str Type of CSV you are requesting. Options:

    • ’paid_contributions’: contains paid, non-refunded contributions to the entity (campaign or organization) you created the credential for, during the specified date range.

    • ’refunded_contributions’: contributions to your entity that were refunded, during the specified date range.

    • ’managed_form_contributions’: contributions made through any form that is

      managed by your entity, during the specified date range - including contributions to other entities via that form if it is a tandem form.

  • date_range_start – str Start of date range to withdraw contribution data (inclusive). Ex: ‘2020-01-01’

  • date_range_end – str End of date range to withdraw contribution data (exclusive). Ex: ‘2020-02-01’

Returns:

Response of POST request; a successful response includes ‘id’, a unique identifier for the CSV being generated.

get_download_url(csv_id=None)[source]

GET request to retrieve download_url for generated CSV.

Parameters:

csv_id – str Unique identifier of the CSV you requested.

Returns:

While CSV is being generated, ‘None’ is returned. When CSV is ready, the method returns the download_url.

poll_for_download_url(csv_id)[source]

Poll the GET request method to check whether CSV generation has finished, signified by the presence of a download_url.

Parameters:

csv_id – str Unique identifier of the CSV you requested.

Returns:

Download URL from which you can download the generated CSV, valid for 10 minutes after retrieval. Null until CSV has finished generating. Keep this URL secure because until it expires, it could be used by anyone to download the CSV.

get_contributions(csv_type: Literal['paid_contributions', 'refunded_contributions', 'managed_form_contributions'], date_range_start: str, date_range_end: str, **csvargs) → Table[source]

Get specified contribution data from CSV API as Parsons table.

Parameters:

  • csv_type –

    str Type of CSV you are requesting. Options:

    • ’paid_contributions’: contains paid, non-refunded contributions to the entity (campaign or organization) you created the credential for, during the specified date range.

    • ’refunded_contributions’: contributions to your entity that were refunded, during the specified date range.

    • ’managed_form_contributions’: contributions made through any form that is

      managed by your entity, during the specified date range - including contributions to other entities via that form if it is a tandem form.

  • date_range_start – str Start of date range to withdraw contribution data (inclusive). Ex: ‘2020-01-01’

  • date_range_end – str End of date range to withdraw contribution data (exclusive). Ex: ‘2020-02-01’

  • **csvargs – Any additional arguments will be passed to Table.from_csv as keyword arguments.

Returns:

parsons.Table

Contents of the generated contribution CSV. List of columns:

  • Receipt ID

  • Date

  • Amount

  • Recurring Total Months

  • Recurrence Number

  • Recipient

  • Fundraising Page

  • Fundraising Partner

  • Reference Code 2

  • Reference Code

  • Donor First Name

  • Donor Last Name

  • Donor Addr1

  • Donor Addr2

  • Donor City

  • Donor State

  • Donor ZIP

  • Donor Country

  • Donor Occupation

  • Donor Employer

  • Donor Email

  • Donor Phone

  • New Express Signup

  • Comments

  • Check Number

  • Check Date

  • Employer Addr1

  • Employer Addr2

  • Employer City

  • Employer State

  • Employer ZIP

  • Employer Country

  • Donor ID

  • Fundraiser ID

  • Fundraiser Recipient ID

  • Fundraiser Contact Email

  • Fundraiser Contact First Name

  • Fundraiser Contact Last Name

  • Partner ID

  • Partner Contact Email

  • Partner Contact First Name

  • Partner Contact Last Name

  • Reserved

  • Lineitem ID

  • AB Test Name

  • AB Variation

  • Recipient Committee

  • Recipient ID

  • Recipient Gov ID

  • Recipient Election

  • Reserved

  • Payment ID

  • Payment Date

  • Disbursement ID

  • Disbursement Date

  • Recovery ID

  • Recovery Date

  • Refund ID

  • Refund Date

  • Fee

  • Recur Weekly

  • ActBlue Express Lane

  • Reserved

  • Card Type

  • Reserved

  • Mobile

  • Recurring Upsell Shown

  • Recurring Upsell Succeeded

  • Double Down

  • Smart Recurring

  • Monthly Recurring Amount

  • Apple Pay

  • Card Replaced by Account Updater

  • ActBlue Express Donor

  • Custom Field 1 Label

  • Custom Field 1 Value

  • Donor US Passport Number

  • Text Message Opt In

  • Gift Identifier

  • Gift Declined

  • Shipping Addr1

  • Shipping City

  • Shipping State

  • Shipping Zip

  • Shipping Country

  • Weekly Recurring Amount

  • Smart Boost Amount

  • Smart Boost Shown

  • Bump Recurring Seen

  • Bump Recurring Succeeded

  • Weekly to Monthly Rollover Date

  • Weekly Recurring Sunset

  • Recurring Type

  • Recurring Pledged

  • Paypal

  • Kind

  • Managed Entity Name

  • Managed Entity Committee Name