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.

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 ActBlue CSV API Authentication 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:

Use API key environment variables
from parsons import ActBlue
actblue = ActBlue()
Pass API keys as arguments
from parsons import ActBlue
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 for the month of January 2020
parsons_table = actblue.get_contributions(
    csv_type='paid_contributions',
    date_range_start='2020-01-01',
    date_range_end='2020-02-01'
)

API

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

Parsons connector for interacting with ActBlue endpoints.

Parameters:

  • actblue_client_uuid (str | None)

  • actblue_client_secret (str | None)

  • actblue_uri (str | None)

  • max_retries (int | None)

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) → None | bool | int | float | str | Sequence[None | bool | int | float | str | Sequence[_JsonType] | Mapping[str, _JsonType]] | Mapping[str, None | bool | int | float | str | Sequence[_JsonType] | Mapping[str, _JsonType]][source]

POST request to ActBlue API to begin generating the CSV.

Parameters:

  • csv_type (Literal['paid_contributions', 'refunded_contributions', 'managed_form_contributions'] | None) –

    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 | None) – Start of date range to withdraw contribution data (inclusive). Ex: ‘2020-01-01’

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

Returns:

Json data returned from POST request. A successful response includes ‘id’, a unique identifier for the CSV being generated.

Return type:

None | bool | int | float | str | Sequence[None | bool | int | float | str | Sequence[_JsonType] | Mapping[str, _JsonType]] | Mapping[str, None | bool | int | float | str | Sequence[_JsonType] | Mapping[str, _JsonType]]

get_download_url(csv_id: str | None = None) → str | None[source]

GET request to retrieve download_url for generated CSV.

Parameters:

csv_id (str | None) – 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.

Return type:

str | None

poll_for_download_url(csv_id: str) → str[source]

Poll the GET request method to check whether CSV generation has finished.

Success is 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. URL is valid for 10 minutes after retrieval. None is returned until CSV has finished generating. Keep this URL secure, because (until it expires) it could be used by anyone to download the CSV.

Return type:

str

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 (Literal['paid_contributions', 'refunded_contributions', 'managed_form_contributions']) –

    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:

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

Return type:

Table