ActionKit

Overview

ActionKit is a platform for advocacy, fundraising, and get-out-the-vote. This Parsons integration with the ActionKit REST API supports fetching, creating, and updating records of campaigns, events, mailers, orders, survey questions, transactions, and users. Bulk upload of new users and user updates is also supported.

Note

Authentication

ActionKit requires HTTP Basic Auth. Clients with an ActionKit account can obtain the domain, username, and password needed to access the ActionKit API. See the ActionKit REST API Authentication documentation for more information on obtaining ActionKit API credentials.

Quickstart

To instantiate the ActionKit class, you can either store your ActionKit API domain, username, and password as environmental variables (ACTION_KIT_DOMAIN, ACTION_KIT_USERNAME, and ACTION_KIT_PASSWORD, respectively) or pass in your domain, username, and password as arguments:

from parsons import ActionKit

# First approach: Use API credentials via environmental variables
ak = ActionKit()

# Second approach: Pass API credentials as arguments
ak = ActionKit(domain='myorg.actionkit.com', username='my_name', password='1234')

You can then call various endpoints:

# Create a new user
ak.create_user(email='john@email', first_name='John', last_name='Smith', city='Boston')

# Fetch user fields
user_fields = ak.get_user(user_id='123')

# Update user fields
ak.update_user(user_id='123', city='New York')

# Delete user
ak.delete_user(user_id='123')

API

class parsons.ActionKit(domain=None, username=None, password=None)

Instantiate the ActionKit class

Args:

domain: str

The ActionKit domain (e.g. myorg.actionkit.com) Not required if ACTION_KIT_DOMAIN env variable set.

username: str

The authorized ActionKit username. Not required if ACTION_KIT_USERNAME env variable set.

password: str

The authorized ActionKit user password. Not required if ACTION_KIT_PASSWORD env variable set.

get_user(user_id)

Get a user.

Args:

user_id: int

The user id of the record to get.

Returns:

User json object

get_user_fields()

Get list of valid user fields that can be passed with the ActionKit.create_user() method.

Returns:

List of user fields

create_user(email, **kwargs)

Create a user.

Args:

email: str

Email for the user

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

User json object

add_phone(user_id, phone_type, phone)

Add a phone number to a user.

Args:

user_id: string

The id of the user.

phone_type: string

The type of the phone (e.g., “Home”).

phone: string

The phone number.

Returns:

Phone json object

delete_actionfield(actionfield_id)

Delete an actionfield.

Args:

actionfield_id: int

The id of the actionfield to delete

Returns:

None

update_user(user_id, **kwargs)

Update a user.

Args:

user_id: int

The user id of the person to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

HTTP response from the patch request

update_phone(phone_id, **kwargs)

Update a phone record.

Args:

phone_id: int

The phone id of the phone to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found at the /rest/v1/phone/schema/ path on any ActionKit instance.

Returns:

HTTP response from the patch request

get_event(event_id)

Get an event.

Args:

event_id: int

The id for the event.

Returns:

dict

Event json object.

get_events(limit=None, **kwargs)

Get multiple events.

Args:

limit: int

The number of events to return. If omitted, all events are returned.

**kwargs:

Optional arguments to pass to the client. A full list can be found in the ActionKit API Documentation.

Additionally, expressions to filter the data can also be provided. For addition info, visit Django’s docs on field lookups.

ak.get_events(name__contains="FirstName")

Returns:

Parsons.Table

The events data.

update_event(event_id, **kwargs)

Update an event.

Args:

event_id: int

The event id of the event to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

None

create_event_field(event_id, name, value)

Create an event field (custom field on an event). Note that if an event field with this name already exists, this will add a second record.

Args:

event_id: int

The id for the event.

name: string

The name of the event field.

value: string

The value of the event field.

Returns:

Event field json object

update_event_field(eventfield_id, name, value)

Update an event field.

Args:

eventfield_id: int

The id of the event field to update.

name: string

The name of the event field.

value: string

The value of the event field.

Returns:

None

get_blackholed_email(email)

Get a blackholed email. A blackholed email is an email that has been prevented from receiving bulk and transactional emails from ActionKit. Documentation.

Args:

email: str

Blackholed email of the record to get.

Returns:

Parsons.Table

The blackholed email data.

blackhole_email(email)

Prevent an email from receiving bulk and transactional emails from ActionKit. Documentation.

Args:

user_id: str

Email to blackhole

Returns:

API location of new resource

delete_user_data(email, **kwargs)

Delete user data.

Args:

email: str

Email of user to delete data

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

API location of anonymized user

delete_user(user_id)

Delete a user.

Args:

user_id: int

The user id of the person to delete

Returns:

None

get_campaign(campaign_id)

Get a campaign.

Args:

campaign_id: int

The campaign id of the record.

Returns:

Campaign json object

get_campaign_fields()

Get list of valid campaign fields that can be passed with the ActionKit.create_campaign() and ActionKit.update_campaign() methods.

Returns:

List of campaign fields

create_campaign(name, **kwargs)

Create a campaign.

Args:

name: str

The name of the campaign to create

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

API location of new resource

search_events_in_campaign(campaign_id, limit=None, order_by='id', ascdesc='asc', filters=None, exclude=None, **kwargs)

Get events in a campaign, with optional search filters.

Args:

campaign_id: int

The id of the event campaign.

limit: int

The maximum number of objects to return.

order_by: string

Event attribute to order the results by. Defaults to id, which will normally be equivalent to ordering by created_at. See ActionKit’s docs on ordering.

ascdesc: string

If “asc” (the default), returns events ordered by the attribute specified by the order_by parameter. If “desc”, returns events in reverse order.

filters: dictionary

A dictionary for filtering by the attributes of the event or related object. Not all attributes are available for filtering, but an eventfield will work. For additional info, visit Django’s docs on field lookups and ActionKit’s docs on the search API.

{
    "title": "Example Event Title",
    "field__name": "example_event_field_name",
    "field__value": "Example event field value",
}

exclude: dictionary

A dictionary for excluding by the attributes of the event or related object. Uses the same format as the filters argument.

**kwargs:

A dictionary of other options for filtering. See ActionKit’s docs on the search API.

Returns:

Parsons.Table

The list of events.

get_event_create_page(event_create_page_id)

Get a event create page.

Args:

event_create_page_id: int

The event create page id of the record to get.

Returns:

Event create page json object

get_event_create_page_fields()

Get list of event create page fields that can be passed with the ActionKit.create_event_create_page().

Returns:

List of event create page fields

create_event_create_page(name, campaign_id, title, **kwargs)

Add an event page to a campaign.

Args:

campaign_id: int

The campaign to assoicate page with

name: str

The name of the page to create

title: str

The title of the page to create

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

API location of new resource

get_event_create_form(event_create_form_id)

Get a event create form.

Args:

event_create_form_id: int

The event create form id of the record to get.

Returns:

Event create form json object

get_event_create_form_fields()

Get list of valid event create form fields that can be passed with the ActionKit.create_event_create_form() method.

Returns:

List of event create form fields

create_event_create_form(page_id, thank_you_text, **kwargs)

Create a event create form.

Args:

page_id: int

The page to associate the form with

thank_you_text: str

Free form thank you text

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

API location of new resource

get_event_signup_page(event_signup_page_id)

Get event signup page.

Args:

event_signup_page_id: int

The event signup page id of the record to get.

Returns:

Event signup page json object

get_event_signup_page_fields()

Get list of valid event signup page fields that can be passed with the ActionKit.create_event_signup_page() method.

Returns:

List of event signup page fields

create_event_signup_page(name, campaign_id, title, **kwargs)

Add an event signup page to a campaign.

Args:

campaign_id: int

The campaign to assoicate page with

name: str

The name of the page to create

title: str

The title of the page to create

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

API location of new resource

get_event_signup_form(event_signup_form_id)

Get a user.

Args:

event_signup_form_id: str

The event signup form id of the record to get.

Returns:

Event signup form json object

get_event_signup_form_fields()

Get list of valid event signup form fields that can be passed with the ActionKit.create_event_signup_form() method.

Returns:

List of event signup form fields

create_event_signup_form(page_id, thank_you_text, **kwargs)

Create a event signup form.

Args:

page_id: int

The page to associate the form with

thank_you_text: str

Free form thank you text

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

API location of new resource

update_event_signup(event_signup_id, **kwargs)

Update an event signup.

Args:

event_signup_id: int

The id of the event signup to update

event_signup_dict: dict

A dictionary of fields to update for the event signup.

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

None

get_mailer(entity_id)

Get a mailer.

Args:

entity_id: int

The entity id of the record to get.

Returns:

Mailer json object

create_mailer(**kwargs)

Create a mailer.

Args:

**kwargs:

Arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

URI of new mailer

copy_mailer(mailer_id)

copy a mailer returns new copy of mailer which should be updatable.

update_mailing(mailer_id, **kwargs)

Update a mailing.

Args:

mailing_id: int

The id of the mailing to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

HTTP response from the patch request

rebuild_mailer(mailing_id)

Rebuild a mailer.

Args:

mailing_id: int

Id of the mailer.

Returns:

URI to poll for progress

queue_mailer(mailing_id)

Queue a mailer.

Args:

mailing_id: int

Id of the mailer.

Returns:

URI to poll for progress

paginated_get(object_type, limit=None, **kwargs)

Get multiple objects of a given type.

Args:

object_type: string

The type of object to search for.

limit: int

The number of objects to return. If omitted, all objects are returned.

**kwargs:

Optional arguments to pass to the client. A full list can be found in the ActionKit API Documentation.

Additionally, expressions to filter the data can also be provided. For addition info, visit Django’s docs on field lookups.

ak.paginated_get(name__contains="FirstName")

Returns:

Parsons.Table

The objects data.

paginated_get_custom_limit(object_type, limit=None, threshold_field=None, threshold_value=None, ascdesc='asc', **kwargs)

Get multiple objects of a given type, stopping based on the value of a field.

Args:

object_type: string

The type of object to search for.

limit: int

The maximum number of objects to return. Even if the threshold value is not reached, if the limit is set, then at most this many objects will be returned.

threshold_field: string

The field used to determine when to stop. Must be one of the options for ordering by.

threshold_value: string

The value of the field to stop at.

ascdesc: string

If “asc” (the default), return all objects below the threshold value. If “desc”, return all objects above the threshold value.

**kwargs:

You can also add expressions to filter the data beyond the limit/threshold values above. For additional info, visit Django’s docs on field lookups.

ak.paginated_get(name__contains="FirstName")

Returns:

Parsons.Table

The objects data.

get_order(order_id)

Get an order.

Args:

order_id: int

The order id of the record to get.

Returns:

User json object

update_order(order_id, **kwargs)

Update an order.

Args:

order_id: int

The id of the order to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

None

update_order_user_detail(user_detail_id, **kwargs)

Update an order user detail.

Args:

user_detail_id: int

The id of the order user detail to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found at the /rest/v1/orderuserdetail/schema/ path on any ActionKit instance.

Returns:

HTTP response from the patch request

get_orderrecurring(orderrecurring_id)

Get an orderrecurring.

Args:

orderrecurring_id: int

The orderrecurring id of the record to get.

Returns:

User json object

cancel_orderrecurring(recurring_id)

Cancel a recurring order.

Args:

recurring_id: int

The id of the recurring order to update (NOT the order_id)

Returns:

None

update_orderrecurring(orderrecurring_id, **kwargs)

Update a recurring order.

Args:

orderrecurring_id: int

The id of the orderrecurring to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

None

get_orders(limit=None, **kwargs)

Get multiple orders.

Args:

limit: int

The number of orders to return. If omitted, all orders are returned.

**kwargs:

Optional arguments to pass to the client. A full list can be found in the ActionKit API Documentation.

Additionally, expressions to filter the data can also be provided. For addition info, visit Django’s docs on field lookups.

ak.get_orders(import_id="my-import-123")

Returns:

Parsons.Table

The orders data.

update_paymenttoken(paymenttoken_id, **kwargs)

Update a saved payment token.

Args:

paymenttoken_id: int

The id of the payment token to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

HTTP response

get_page_followup(page_followup_id)

Get a page followup.

Args:

page_followup_id: int

The user id of the record to get.

Returns:

Page followup json object

get_page_followup_fields()

Get list of valid page followup fields that can be passed with the ActionKit.create_page_followup() method.

Returns:

List of page followup fields

create_page_followup(signup_page_id, url, **kwargs)

Add a page followup.

Args:

signup_page_id: int

The signup page to associate the followup page with

url: str

URL of the folloup page

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

API location of new resource

get_survey_question(survey_question_id)

Get a survey question.

Args:

survey_question_id: int

The survey question id of the record to get.

Returns:

Survey question json object

update_survey_question(survey_question_id, **kwargs)

Update a survey question.

Args:

survey_question_id: int

The id of the survey question to update

survey_question_dict: dict

A dictionary of fields to update for the survey question.

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

None

create_transaction(**kwargs)

Create a transaction.

Args:

**kwargs:

Optional arguments and fields to pass to the client.

Returns:

Transaction json object

update_transaction(transaction_id, **kwargs)

Update a transaction.

Args:

transaction_id: int

The id of the transaction to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

None

get_transactions(limit=None, **kwargs)

Get multiple transactions.

Args:

limit: int

The number of transactions to return. If omitted, all transactions are returned.

**kwargs:

Optional arguments to pass to the client. A full list can be found in the ActionKit API Documentation.

Additionally, expressions to filter the data can also be provided. For addition info, visit Django’s docs on field lookups.

ak.get_transactions(order="order-1")

Returns:

Parsons.Table

The transactions data.

create_generic_action(page, email=None, ak_id=None, **kwargs)

Post a generic action. One of ak_id or email is a required argument.

Args:

page:

The page to post the action. The page short name.

email:

The email address of the user to post the action.

ak_id:

The action kit id of the record.

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found in the ActionKit API Documentation.

Returns:

dict

The response json

update_import_action(action_id, **kwargs)

Update an import action.

Args:

action_id: int

The action id of the import action to update

**kwargs:

Optional arguments and fields to pass to the client. A full list can be found at the /rest/v1/importaction/schema/ path on any ActionKit instance.

Returns:

HTTP response from the patch request

bulk_upload_csv(csv_file, import_page, autocreate_user_fields=False, user_fields_only=False)

Bulk upload a csv file of new users or user updates. If you are uploading a table object, use bulk_upload_table instead. See ActionKit User Upload Documentation Be careful that blank values in columns will overwrite existing data.

If you get a 500 error, try sending a much smaller file (say, one row), which is more likely to return the proper 400 with a useful error message

Args:

import_page: str

The page to post the action. The page short name.

csv_file: str or buffer

The csv (optionally zip’d) file path or a file buffer object A user_id or email column is required. ActionKit rejects files that are larger than 128M

autocreate_user_fields: bool

When True columns starting with “user_” will be uploaded as user fields. See the autocreate_user_fields documentation.

user_fields_only: bool

When uploading only an email/user_id column and user_ user fields, ActionKit has a fast processing path. This doesn’t work, if you upload a zipped csv though.

Returns:

dict

success: whether upload was successful progress_url: an API URL to get progress on upload processing res: requests http response object

bulk_upload_table(table, import_page, autocreate_user_fields=0, no_overwrite_on_empty=False, set_only_columns=None)

Bulk upload a table of new users or user updates. See ActionKit User Upload Documentation Be careful that blank values in columns will overwrite existing data.

Tables with only an identifying column (user_id/email) and user_ user fields will be fast-processed – this is useful for setting/updating user fields.

Note

If you get a 500 error, try sending a much smaller file (say, one row), which is more likely to return the proper 400 with a useful error message

Args:

import_page: str

The page to post the action. The page short name.

table: Table Class

A Table of user data to bulk upload A user_id or email column is required.

autocreate_user_fields: bool

When True columns starting with “user_” will be uploaded as user fields. ActionKit. See the autocreate_user_fields documentation.

no_overwrite_on_empty: bool

When uploading user data, ActionKit will, by default, take a blank value and overwrite existing data for that user. This can be undesirable, if the goal is to only send updates. Setting this to True will divide up the table into multiple upload batches, changing the columns uploaded based on permutations of empty columns.

set_only_columns: list

This is similar to no_overwrite_on_empty but restricts to a specific set of columns which, if blank, should not be overwritten.

Returns:

dict

success: bool – whether upload was successful (individual rows may not have been) results: [dict] – This is a list of the full results.

progress_url and res for any results

collect_upload_errors(result_array)

Collect any upload errors as a list of objects from bulk_upload_table ‘results’ key value. This waits for uploads to complete, so it may take some time if you uploaded a large file. Args:

result_array: list

After receiving a dict back from bulk_upload_table you may want to see if there were any errors in the uploads. If you call collect_upload_errors(result_array) it will iterate across each of the uploads fetching the final result of e.g. /rest/v1/uploaderror?upload=123

Returns:

[dict]

message: str – error message upload: str – upload progress API path e.g. “/rest/v1/upload/123456/” id: int – upload error record id (different than upload id)