CapitolCanary

Overview

CapitolCanary is a digital advocacy tool used by progressive organizations. This class allows you to interact with the tool by leveraging their API.

Note

Authentication: You will need to email CapitolCanary to request credentials to access the API. The credentials consist of an app ID and an app key.

Quick Start

To instantiate the CapitolCanary class, you can either pass in the app ID and app key as arguments or set the CAPITOLCANARY_APP_ID and CAPITOLCANARY_APP_KEY environmental variables.

from parsons import CapitolCanary

# Instantiate the class using environment variables
cc = CapitolCanary()

# Get all advocates updated in the last day
import datetime
today = datetime.datetime.utcnow()
yesterday = today - datetime.timedelta(days=1)

# get_advocates returns a dictionary that maps the advocate data (e.g. phones) to a parsons
# Table with the data for each advocate
advocates_data = cc.get_advocates(updated_since=yesterday)

# For all of our advocates' phone numbers, opt them into SMS
for phone in advocates_data['phones']:
    phone_number = phone['phones_address']
    # Only update phone numbers that aren't already subscribed
    if phone['subscribed']:
        cc.update_advocate(phone['advocate_id'], phone=phone_number, sms_opt_in=True)

API

class parsons.CapitolCanary(app_id=None, app_key=None)[source]

Instantiate CapitolCanary Class

Args:

app_id: str: The CapitolCanary provided application id. Not required if CAPITOLCANARY_APP_ID env variable set.
app_key: str: The CapitolCanary provided application key. Not required if CAPITOLCANARY_APP_KEY env variable set.

Returns:

CapitolCanary Class

get_advocates(state=None, campaign_id=None, updated_since=None, page=None)[source]

Return advocates (person records).

If no page is specified, the method will automatically paginate through the available advocates.

Args:

state: str: Filter by US postal abbreviation for a state or territory e.g., “CA” “NY” or “DC”
campaign_id: int: Filter to specific campaign
updated_since: str or int or datetime: Fetch all advocates updated since the date provided; this can be a datetime object, a UNIX timestamp, or a date string (ex. ‘2014-01-05 23:59:43’)
page: int: Page number of data to fetch; if this is specified, call will only return one page.

Returns:

A dict of parsons tables:

emails
phones
memberships
tags
ids
fields
advocates

get_campaigns(state=None, zip=None, include_generic=False, include_private=False, include_content=True)[source]

Returns a list of campaigns

Args:

state: str: Filter by US postal abbreviation for a state or territory e.g., “CA” “NY” or “DC”
zip: int: Filter by 5 digit zip code
include_generic: boolean: When filtering by state or ZIP code, include unrestricted campaigns
include_private: boolean: If true, will include private campaigns in results
include_content: boolean: If true, include campaign content fields, which may vary. This may cause sync errors.

Returns:

Parsons Table: See Parsons Table for output options.

create_advocate(campaigns, first_name=None, last_name=None, email=None, phone=None, address1=None, address2=None, city=None, state=None, zip5=None, sms_optin=None, email_optin=None, sms_optout=None, email_optout=None, **kwargs)[source]

Create an advocate.

If you want to opt an advocate into or out of SMS / email campaigns, you must provide the email address or phone number (accordingly).

The list of arguments only partially covers the fields that can be set on the advocate. For a complete list of fields that can be updated, see the CapitolCanary API documentation.

Args:

campaigns: list: The ID(s) of campaigns to add the advocate to
first_name: str: Optional; The first name of the advocate
last_name: str: Optional; The last name of the advocate
email: str: Optional; An email address to add for the advocate. One of email or phone is required.
phone: str: Optional; An phone # to add for the advocate. One of email or phone is required.
address1: str: Optional; The first line of the advocates’ address
address2: str: Optional; The second line of the advocates’ address
city: str: Optional; The city of the advocates address
state: str: Optional; The state of the advocates address
zip5: str: Optional; The 5 digit Zip code of the advocate
sms_optin: boolean: Optional; Whether to opt the advocate into receiving text messages; an SMS confirmation text message will be sent. You must provide values for the phone and campaigns arguments.
email_optin: boolean: Optional; Whether to opt the advocate into receiving emails. You must provide values for the email and campaigns arguments.
sms_optout: boolean: Optional; Whether to opt the advocate out of receiving text messages. You must provide values for the phone and campaigns arguments. Once an advocate is opted out, they cannot be opted back in.
email_optout: boolean: Optional; Whether to opt the advocate out of receiving emails. You must provide values for the email and campaigns arguments. Once an advocate is opted out, they cannot be opted back in.
**kwargs:: Additional fields on the advocate to update

Returns:

The int ID of the created advocate.

update_advocate(advocate_id, campaigns=None, email=None, phone=None, sms_optin=None, email_optin=None, sms_optout=None, email_optout=None, **kwargs)[source]

Update the fields of an advocate.

If you want to opt an advocate into or out of SMS / email campaigns, you must provide the email address or phone number along with a list of campaigns.

The list of arguments only partially covers the fields that can be updated on the advocate. For a complete list of fields that can be updated, see the CapitolCanary API documentation.

Args:

advocate_id: integer: The ID of the advocate being updates
campaigns: list: Optional; The ID(s) of campaigns to add the user to
email: str: Optional; An email address to add for the advocate (or to use when opting in/out)
phone: str: Optional; An phone # to add for the advocate (or to use when opting in/out)
sms_optin: boolean: Optional; Whether to opt the advocate into receiving text messages; an SMS confirmation text message will be sent. You must provide values for the phone and campaigns arguments.
email_optin: boolean: Optional; Whether to opt the advocate into receiving emails. You must provide values for the email and campaigns arguments.
sms_optout: boolean: Optional; Whether to opt the advocate out of receiving text messages. You must provide values for the phone and campaigns arguments. Once an advocate is opted out, they cannot be opted back in.
email_optout: boolean: Optional; Whether to opt the advocate out of receiving emails. You must provide values for the email and campaigns arguments. Once an advocate is opted out, they cannot be opted back in.
**kwargs:: Additional fields on the advocate to update