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.capitol_canary.capitol_canary.CapitolCanary(app_id=None, app_key=None)[source]¶

Instantiate CapitolCanary Class

Parameters:

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: str | int | datetime | None = None, page=None)[source]¶

Return advocates (person records).

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

Parameters:

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:

dict[Table]

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

Parameters:

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.

Parameters:

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:

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.

Parameters:

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