Phone2Action¶
Overview¶
Phone2Action 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 Phone2Action to request credentials to access the API. The credentials consist of an app ID and an app key.
Quick Start¶
To instantiate the Phone2Action
class, you can either pass in the app ID and app key as arguments or set the
PHONE2ACTION_APP_ID
and PHONE2ACTION_APP_KEY
environmental variables.
from parsons import Phone2Action
# Instantiate the class using environment variables
p2a = Phone2Action()
# 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 = p2a.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']:
p2a.update_advocate(phone['advocate_id'], phone=phone_number, sms_opt_in=True)
API¶
-
class
parsons.
Phone2Action
(app_id=None, app_key=None)[source]¶ Instantiate Phone2Action Class
- Args:
- app_id: str
- The Phone2Action provided application id. Not required if
PHONE2ACTION_APP_ID
env variable set. - app_key: str
- The Phone2Action provided application key. Not required if
PHONE2ACTION_APP_KEY
env variable set.
- Returns:
- Phone2Action 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 Phone2Action 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
orphone
is required. - phone: str
- Optional; An phone # to add for the advocate. One of
email
orphone
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
andcampaigns
arguments. - email_optin: boolean
- Optional; Whether to opt the advocate into receiving emails. You must provide
values for the
email
andcampaigns
arguments. - sms_optout: boolean
- Optional; Whether to opt the advocate out of receiving text messages. You must
provide values for the
phone
andcampaigns
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
andcampaigns
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 Phone2Action 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
andcampaigns
arguments. - email_optin: boolean
- Optional; Whether to opt the advocate into receiving emails. You must provide
values for the
email
andcampaigns
arguments. - sms_optout: boolean
- Optional; Whether to opt the advocate out of receiving text messages. You must
provide values for the
phone
andcampaigns
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
andcampaigns
arguments. Once an advocate is opted out, they cannot be opted back in. - **kwargs:
- Additional fields on the advocate to update