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_client_uuid=None, actblue_client_secret=None, actblue_uri=None)[source]

Instantiate class.

Args:

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.

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

post_request(csv_type=None, date_range_start=None, date_range_end=None)[source]

POST request to ActBlue API to begin generating the CSV.

Args:

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.

Args:

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.

Args:

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, date_range_start, date_range_end)[source]

Get specified contribution data from CSV API as Parsons table.

Args:

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:

Contents of the generated contribution CSV as a Parsons table.