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