PDI

Overview

PDI is a political data provider that is primarily active in California. This class allows you to interact with the PDI API .

This Parsons connector provides methods to fetch lists of acquisition types, flag IDs, questions, universes, and flags given start and end dates.

Note

Authentication

A user name, password, and API token are required to instantiate the PDI class. To obtain log in credentials, request a PDI API account from support@politicaldata.com. The administrative process usually takes a couple of hours.

Quickstart

To instantiate the PDI class, you can either store your PDI API username, password, and API token as environmental variables (PDI_USERNAME, PDI_PASSWORD, and PDI_API_TOKEN, respectively) or pass them in as arguments:

from parsons import PDI

# First approach: Use API credentials via environmental variables
pdi = PDI()

# Second approach: Pass API credentials as arguments
pdi = PDI(username='my_username', password='my_password', api_token='my_token')

# Get all contacts (flag IDs) available from PDI
pdi.get_flag_ids()

# Get all flags since the beginning of 2020
pdi.get_flags(start_date='2020-01-01')

PDI Class

class parsons.PDI(username=None, password=None, api_token=None, qa_url=False)[source]
add_email(contact_id: int, email: str, primary: bool = True)

Add an email address to a contact.

Parameters:

  • contact_id (int) – The ID of the contact.

  • email (str) – The email address to add.

  • primary (bool) – Whether this is the contact’s primary email.

Returns:

Response from PDI

Return type:

dict

add_phone(contact_id: int, phone_number: str, phone_type: Literal['Home', 'Work', 'Direct', 'Mobile', 'Fax', 'Other'] = 'Mobile', primary: bool = True, extension: str = '')

Add a phone number to a contact.

Parameters:

  • contact_id (int)

  • phone_number (str)

  • phone_type (str) – Options are “Home”, “Work”, “Direct”, “Mobile”, “Fax”, and “Other”. Defaults to “Mobile”.

  • primary (bool) – Whether this is the contact’s primary phone number. Defaults to True.

  • extension (str) – Defaults to “”.

Returns:

dict

Response from PDI

create_acquisition_type(acquisition_type: str, acquisition_description: str, acquisition_method: Literal['Phone', 'Canvass', 'Mail', 'IVR', 'Text Message', 'Email', 'Event', 'Online', 'Social', 'Site', 'Other Method'], page_default: Literal['Lookup', 'WalkList', 'PhoneList', 'PhoneBank', 'Canvassing', 'Import'] | None = None)

Create a new Acquisition Type

Parameters:

  • acquisition_type (string) – The acquisition type

  • acquisition_description (string) – The acquisition description

  • acquisition_method (string) – The acquisition method Options are: - “Phone” - “Canvass” - “Mail” - “IVR” - “Text Message” - “Email” - “Event” - “Online” - “Social” - “Site” - “Other Method” ,

  • pageDefault (string, optional) – The page default. - “Lookup” (Lookup Page) - “WalkList” (Create Lists & Files - Walk List) - “PhoneList” (Create Lists & Files - Phone List) - “PhoneBank” (Online Phone Bank) - “Canvassing” (Mobile Canvassing Device) - “Import” (Imports)

create_activity(activity_name: str, canvassing_shift: bool)

Create a New Activity

Parameters:

  • activity_name – str The activity name

  • canvassing_shift – bool The canvassing shift

create_activity_assignment(eventactivityid: str, contact_id: str, status: Literal['Yes', 'No', 'Maybe', 'Scheduled', 'Invited', 'Cancelled', 'No-Show', 'Completed', ''], completed: bool, confirmed=False, specific_occurrence_start=None)

Create an activity assignment

Parameters:

  • eventactivityid – str The ID of the specific event activity you’d like to assign a contact

  • contact_id – str The ID of the contact to which the assignment belongs

  • status – str Options are: “Yes”, “No”, “Maybe”, “Scheduled”, “Invited”, “Cancelled”, “No-Show”, “Completed”, and “”

  • completed – boolean Indicates whether contact attended event

  • confirmed – boolean Indicates whether invitation confirmed they will attend the event

  • specific_occurrence_start – str If invitation is for a specific occurrence of a recurring event, then the start datetime of the event in UTC formatted as yyyy-MM-ddTHH:mm:ss.fffZ

Returns:

dict

Response from PDI in dictionary object

create_contact(name_prefix='', first_name='', last_name='', middle_name='', name_suffix='', nickname='', occupation='', employer='', volunteer_status: Literal['Prospect', 'Active', 'Inactive', 'None', ''] = '', donor_status: Literal['Prospect', 'Active', 'Inactive', 'None', ''] = '', member_status: Literal['Prospect', 'Active', 'Inactive', 'None', ''] = '', date_of_birth=None, gender: Literal['F', 'M', 'U'] | None = None, email='', pdi_id=None)

Create new contact

Parameters:

  • name_prefix (str) – Prefix for the name.

  • first_name (str) – The contact’s first name.

  • last_name (str) – The contact’s last name.

  • middle_name (str) – The contact’s middle name.

  • name_suffix (str) – Suffix for the name.

  • nickname (str) – The contact’s nickname.

  • occupation (str) – The contact’s occupation.

  • employer (str) – The contact’s employer.

  • volunteer_status (str) – Options are “Prospect”, “Active”, “Inactive”, “None”, or “”.

  • donor_status (str) – Options are “Prospect”, “Active”, “Inactive”, “None”, or “”.

  • member_status (str) – Options are “Prospect”, “Active”, “Inactive”, “None”, or “”.

  • date_of_birth (str, optional) – Format allowed yyyy-MM-dd.

  • gender (str, optional) – Options are “F”, “M”, or “U”.

  • email (str, optional) – The contact’s email.

  • pdi_id (str, optional) – Ignored when updating.

Returns:

A Table containing the response data.

Return type:

parsons.Table

create_event(calendar_id: str, location_id: str, event_name: str, start_datetime: str, end_datetime: str, description=None, all_day=False, recurrencetype: Literal['daily', 'weekly', 'monthly'] | None = None, recurrence_end_datetime=None, host_phone=None, host_email=None, website=None)

Create event in a specified calendar

Parameters:

  • calendar_id – str The calendar in which you’d like to create an event

  • location_id – str The unique ID of the PDI location this event took place/is to take place at

  • event_name – str The name of your event

  • description – str A short description for your event

  • start_datetime – str The start datetime of the event in UTC timezone formatted as yyyy-MM-ddThh:mm:ss.fffZ

  • end_datetime – str The end date formatted like start_datetime

  • is_all_day – bool set to True if event is an all day event. Defaults to False

  • recurrencetype – str Either ‘daily’, ‘weekly’, or ‘monthly’. Defaults to None

  • recurrence_end_datetime – str The end time of the last recurrence of the event formatted as yyyy-MM-ddThh:mm:ss.fffZ

  • host_phone – str An optional contact phone number for the host. Defaults to None

  • host_email – str An optional contact email for the host. Defaults to None

  • website – str An optional website for the event. Defualts to None

Returns:

dict

Response from PDI in dictionary object

create_event_activity(calendar_id: str, event_id: str, activity_id: str, location_id: str, activity_name: str, start_datetime: str, end_datetime: str, description=None, recurrencetype: Literal['daily', 'weekly', 'monthly'] | None = None, recurrence_end_datetime=None, signup_goal=None)

Create event in a specified calendar with an associated activity

Parameters:

  • calendar_id – str The unique ID of the calendar in which you’d like to create an event

  • event_id – str The unique ID of the event this activity is to be associated with

  • activity_id – The unique ID of the activity type you’d like to add to the event

  • location_id – str The unique ID of the PDI location where this event took place/is to take place

  • activity_name – str The name of your activity. e.g. ‘Pictionary!’

  • description – str A short description for your event activity

  • start_datetime – str The start datetime of the event in UTC timezone formatted as yyyy-MM-ddThh:mm:ss.fffZ

  • end_datetime – str The end date formatted like start_datetime

  • recurrencetype – str Either ‘daily’, ‘weekly’, or ‘monthly’. Defaults to None

  • recurrence_end_datetime – str The end time of the last recurrence of the event formatted as yyyy-MM-ddThh:mm:ss.fffZ

  • signup_goal – int The goal of how many people you want to complete the activity

Returns:

dict

Response from PDI in dictionary object

create_event_with_activity(calendar_id: str, location_id: str, activity_id: str, event_name: str, activity_name: str, start_datetime: str, end_datetime: str, description=None, all_day=False, recurrencetype: Literal['daily', 'weekly', 'monthly'] | None = None, recurrence_end_datetime=None, host_phone=None, host_email=None, website=None, signup_goal=None)

Create event in a specified calendar with an associated activity.

The activty will be assigned the same start, end time, and recurrance settings as the event.

Parameters:

  • calendar_id – str The unique ID of the calendar in which you’d like to create an event

  • location_id – str The unique ID of the PDI location whek this event took place/is to take place

  • activity_id – The unique ID of the activity type you’d like to add to the event

  • event_name – str The name of your event

  • activity_name – str The name of your activity. e.g. ‘Pictionary!’

  • description – str A short description for your event

  • start_datetime – str The start datetime of the event in UTC timezone formatted as yyyy-MM-ddThh:mm:ss.fffZ

  • end_datetime – str The end date formatted like start_datetime

  • bool (is_all_day =) – set to True if event is an all day event. Defaults to False

  • recurrencetype – str Either ‘daily’, ‘weekly’, or ‘monthly’. Defaults to None

  • recurrence_end_datetime – str The end time of the last recurrence of the event formatted as yyyy-MM-ddThh:mm:ss.fffZ

  • host_phone – str An optional contact phone number for the host. Defaults to None

  • host_email – str An optional contact email for the host. Defaults to None

  • website – str An optional website for the event. Defualts to None

  • signup_goal – int The goal of how many people you want to complete the activity

Returns:

dict

Response from PDI in dictionary object

create_flag_id(flag_id: Literal['AMM', 'BNH', 'BNM', 'DEAD', 'DNC', 'DNR', 'ENDR', 'GTD', 'HH', 'L2VT', 'LBO', 'LM', 'LO', 'LS', 'LSD', 'LSR', 'MAYBE', 'MOV', 'NAH', 'NO', 'REF', 'SO', 'SS', 'SUP', 'U', 'UL2VT', 'VL2VT', 'VOL', 'VTD'], is_default, flag_description=None, compile=None)

Save a new flag id.

Parameters:

  • flag_id – str The flag id type. One of: “AMM”, “BNH”, “BNM”, “DEAD”, “DNC”, “DNR”, “ENDR”, “GTD”, “HH”, “L2VT”, “LBO”, “LM”, “LO”, “LS”, “LSD”, “LSR”, “MAYBE”, “MOV”, “NAH”, “NO”, “REF”, “SO”, “SS”, “SUP”, “U”, “UL2VT”, “VL2VT”, “VOL”, “VTD”.

  • is_default – bool The default.

  • flag_description – str (Optional) The flag id description.

  • compile – str (Optional) The compile.

Returns:

str

The identifier for the new flag id.

create_flags(flag_list: list)

Save a list of flags.

Parameters:

  • flag_list – list[dict]

  • code-block: (..) –

    python: [

    {

    “pdiId”: “string”, “flagEntryDate”: “An end date formatted like yyyy-MM-dd.”, “acquisitionTypeId”: “string”, “flagId”: “string”, “questionId”: “string”, “contactId”: “string”

    }

    ]

create_invitation(event_id: str, contact_id: str, status: Literal['Yes', 'No', 'Maybe', 'Scheduled', 'Invited', 'Cancelled', 'No-Show', 'Completed', ''], attended: bool, confirmed=False, specific_occurrence_start=None)

Create a PDI event invitation indicating a contact has been registered for an event

Parameters:

  • event_id – str The ID of the event to write the RSVP to

  • contact_id – str The ID of the contact to which the invitation belongs

  • status – str Options are: “Yes”, “No”, “Maybe”, “Scheduled”, “Invited”, “Cancelled”, “No-Show”, “Completed”, and “”

  • attended – boolean Indicates whether contact attended event

  • confirmed – boolean Indicates whether invitation confirmed they will attend the event. Defaults to False

  • specific_occurrence_start – str If invitation is for a specific occurrence of a recurring event, then the start datetime of the event in UTC formatted as yyyy-MM-ddTHH:mm:ss.fffZ

Returns:

dict

Response from PDI in dictionary object

create_location(address: str, name: str)

Create a new PDI address

Parameters:

  • address – str A full address including street number, city, state, and zip.

  • name – str The name of the location. E.g. “The Overlook Hotel”

Returns:

dict

Response from PDI in dictionary object

create_question(question: str, type: str, category: str, answer_options: list, question_label: str | None = None, question_description: str | None = None, candidate_issue_id: str | None = None, default: bool = True, *args)

Create a new question.

Parameters:

  • question (str)

  • type (str)

  • category (str)

  • answer_options (list[dict[str, str]) – 

    [
    {
    "id": "string",
    "flagId": "string",
    "displayDescription": "string",
    "displayCode": "string"
    }
]

  • question_label (str, optional)

  • question_description (str, optional)

  • candidate_issue_id (str, optional)

  • default (bool, optional) – Defaults to True

delete_acquisition_type(id: str)

Delete a Acquisition Type by id.

Parameters:

id – str The Acquisition Type id

delete_contact(id: str)

Delete a Question by id.

Parameters:

id – str The Question id

delete_flag(id: str)

Delete a Flag by id.

Parameters:

id – str The Flag id

delete_flag_id(id)

Delete a flag id.

NOTE: The function returns True (even if the id doesn’t exist) unless there is an error.

Parameters:

id – str The flag id identifier.

Returns:

bool

True if the operation is successful.

get_acquisition_type(id: str)

Get a Acquisition Type by id.

Parameters:

id – str The Acquisition Type id

Returns:

parsons.Table

get_acquisition_types(limit: int | None = None)

Get a list of Acquisition Types.

Parameters:

limit – int Specify limit to return.

Returns:

parsons.Table

get_activities(limit: int | None = None)

Get a list of Activities.

Parameters:

limit – int Specify limit to return.

Returns:

parsons.Table

get_activity(id: str)

Get a Activity by id.

Parameters:

id – str The Activity id

Returns:

parsons.Table

get_calendars(limit=None)

Gets a list of calendars.

Parameters:

limit – int Specify limit to return (max=2000)

Returns:

parsons.Table

id, name, description, and timeZone records

Documentation Reference:

https://api.bluevote.com/docs/index#!/Calendars/Calendars_GetAll

get_contact(id: str)

Get a Contact by id.

Parameters:

id – str The Contact id

Returns:

parsons.Table

get_contacts(email: str | None = None, phone: str | None = None, first_name: str | None = None, last_name: str | None = None, zip_code: str | None = None, search_by_email: bool = False, limit: int | None = None)

Get a list of Contacts.

Parameters:

  • email (str)

  • phone (str)

  • first_name (str)

  • last_name (str)

  • zip_code (str)

  • search_by_email (bool) – whether to search using email address

  • limit (int) – The number of contacts to return

Returns:

parsons.Table

get_event_activities(start_date, end_date, limit=None)

Get a list of event activities.

Parameters:

  • start_date – str Earliest records to be returned in the API response Per the API docs, use “YYYY-MM-DD” format

  • end_date – str Latest records to be returned in the API response. Per the API docs, use “YYYY-MM-DD” format

  • limit – int Specify limit to return (max=2000)

Returns:

parsons.Table

Event activity responses

Documentation Reference:

https://api.bluevote.com/docs/index#!/EventActivities/EventActivities_GetAll

get_event_activity_assignments(start_date, end_date, expand, limit=None)

Get a list of event activity assignments.

Parameters:

  • start_date – str Earliest records to be returned in the API response Per the API docs, use “YYYY-MM-DD” format

  • end_date – str Latest records to be returned in the API response. Per the API docs, use “YYYY-MM-DD” format

  • expand – bool Parameter to determine if we return the list of shift assigments expanded or not

  • limit – int Specify limit to return (max=2000)

Returns:

parsons.Table

Event activity assignment responses

Documentation Reference:

https://api.bluevote.com/docs/index#/EventActivityAssignments

get_event_invitations(event_id: str, expand=True, limit=None)

Get a table of PDI event invitations for a specified event

Parameters:

  • event_id – str ID of event for which you want invitations

  • expand – bool If True returns columns for contact (and all contact info) and event)

Returns:

parsons.Table

All requested event invitation data.

get_events(first_event_date: str, last_event_date: str, limit=None)

Get a table of PDI events in a given time frame

Parameters:

  • first_event_date – str First date in the timeframe from which you want events formatted at ‘yyy-MM-dd’

  • last_event_date – str Last date in the timeframe from which you want events formatted at ‘yyy-MM-dd’

  • limit – int The max number of events to return

Returns:

parsons.Table

All requested events data.

get_flag_id(id)

Get a specified flag id.

Parameters:

id – str The flag id identifier.

Returns:

dict

FlagID object.

get_flag_ids(limit=None)

Get a list of flag ids.

Parameters:

limit – int Specify limit to return.

Returns:

parsons.Table

get_flags(start_date, end_date, limit=None)

Get a list of flags.

Parameters:

  • start_date – str A start date formatted like yyyy-MM-dd.

  • end_date – str An end date formatted like yyyy-MM-dd.

  • limit – int Specify limit to return.

Returns:

parsons.Table

get_locations(limit=None)

Get a list of PDI Locations

Parameters:

limit – int The max number of locations to return

Returns:

parsons.Table

All requested location data.

get_question(id: str)

Get a Question by id.

Parameters:

id – str The Question id

Returns:

parsons.Table

get_questions(limit=None)

Get a list of Questions.

Parameters:

limit – int Specify limit to return.

Returns:

parsons.Table

get_universe(id: str)

Get a Universe by id.

Parameters:

id – str The Universe id

Returns:

parsons.Table

get_universes(limit=None)

Get a list of Universes.

Parameters:

limit – int The number of universes to return.

Returns:

parsons.Table

update_acquisition_type(id: str, acquisition_type: str, acquisition_description: str, acquisition_method: Literal['Phone', 'Canvass', 'Mail', 'IVR', 'Text Message', 'Email', 'Event', 'Online', 'Social', 'Site', 'Other Method'], page_default: Literal['Lookup', 'WalkList', 'PhoneList', 'PhoneBank', 'Canvassing', 'Import'] | None = None)

Update Acquisition Type

Parameters:

  • acquisition_type (string) – The acquisition type

  • acquisition_description (string) – The acquisition description

  • acquisition_method (string) – The acquisition method Options are: - “Phone” - “Canvass” - “Mail” - “IVR” - “Text Message” - “Email” - “Event” - “Online” - “Social” - “Site” - “Other Method” ,

  • pageDefault (string, optional) – The page default. - “Lookup” (Lookup Page) - “WalkList” (Create Lists & Files - Walk List) - “PhoneList” (Create Lists & Files - Phone List) - “PhoneBank” (Online Phone Bank) - “Canvassing” (Mobile Canvassing Device) - “Import” (Imports)

update_activity(id: str, activity_name: str, canvassing_shift: str)

Update an Activity

Parameters:

  • id – str Activity id

  • activity_name – str The activity name

  • canvassing_shift – bool The canvassing shift

update_activity_assignment(activityassignmentid: str, eventactivityid: str, contact_id: str, status: Literal['Yes', 'No', 'Maybe', 'Scheduled', 'Invited', 'Cancelled', 'No-Show', 'Completed', ''] = None, completed=None, confirmed=None, specific_occurrence_start=None)

Create an activity assignment

Parameters:

  • activityassignmentid – str Id of the specific event activity assignment you want to modify

  • eventactivityid – str The ID of the specific event activity you’d like to assign a contact

  • contact_id – str The ID of the contact to which the assignment belongs

  • status – str Options are: “Yes”, “No”, “Maybe”, “Scheduled”, “Invited”, “Cancelled”, “No-Show”, “Completed”, and “”

  • completed – boolean Indicates whether contact attended event

  • confirmed – boolean Indicates whether invitation confirmed they will attend the event

  • specific_occurrence_start – str If invitation is for a specific occurrence of a recurring event, then the start datetime of the event in UTC formatted as yyyy-MM-ddTHH:mm:ss.fffZ

Returns:

dict

Response from PDI in dictionary object

update_contact(id, first_name, last_name, name_prefix='', middle_name='', name_suffix='', nickname='', occupation='', employer='', volunteer_status: Literal['Prospect', 'Active', 'Inactive', 'None', ''] = '', donor_status: Literal['Prospect', 'Active', 'Inactive', 'None', ''] = '', member_status: Literal['Prospect', 'Active', 'Inactive', 'None', ''] = '', date_of_birth=None, gender: Literal['F', 'M', 'U'] | None = None)

Update Contact

Parameters:

  • name_prefix (str)

  • first_name (str)

  • middle_name (str)

  • last_name (str)

  • name_suffix (str)

  • nickname (str)

  • occupation (str)

  • employer (str)

  • volunteer_status (str) – Options are “Prospect”, “Active”, “Inactive”, “None”, “”

  • donor_status (str) – Options are “Prospect”, “Active”, “Inactive”, “None”, “”

  • member_status (str) – Options are “Prospect”, “Active”, “Inactive”, “None”, “”

  • date_of_birth (str, optional) – Format must be yyyy-MM-dd

  • gender (str, optional) – Options are “F”, “M”, “U”

Returns:

See Parsons Table for output options

Return type:

parsons.Table

update_flag_id(id, flag_id: Literal['AMM', 'BNH', 'BNM', 'DEAD', 'DNC', 'DNR', 'ENDR', 'GTD', 'HH', 'L2VT', 'LBO', 'LM', 'LO', 'LS', 'LSD', 'LSR', 'MAYBE', 'MOV', 'NAH', 'NO', 'REF', 'SO', 'SS', 'SUP', 'U', 'UL2VT', 'VL2VT', 'VOL', 'VTD'], is_default, flag_description=None, compile=None)

Update a flag id.

Parameters:

  • id – str The flag id identifier.

  • flag_id – str The flag id type. One of: “AMM”, “BNH”, “BNM”, “DEAD”, “DNC”, “DNR”, “ENDR”, “GTD”, “HH”, “L2VT”, “LBO”, “LM”, “LO”, “LS”, “LSD”, “LSR”, “MAYBE”, “MOV”, “NAH”, “NO”, “REF”, “SO”, “SS”, “SUP”, “U”, “UL2VT”, “VL2VT”, “VOL”, “VTD”.

  • is_default – bool The default.

  • flag_description – str (Optional) The flag id description.

  • compile – str (Optional) The compile.

Returns:

str

The identifier for the udpated flag id.

update_invitation(invitation_id: str, event_id: str, contact_id: str, status: Literal['Yes', 'No', 'Maybe', 'Scheduled', 'Invited', 'Cancelled', 'No-Show', 'Completed', ''] = None, attended=None, confirmed=None, specific_occurrence_start=None)

Modify a PDI event invitation

Parameters:

  • invitation_id – str The ID of the event invitation

  • event_id – str The ID of the event that corresponds to the invitation

  • contact_id – str The ID of the contact to which the invitation belongs

  • status – str Options are: “Yes”, “No”, “Maybe”, “Scheduled”, “Invited”, “Cancelled”, “No-Show”, “Completed”, and “”

  • attended – boolean Indicates whether contact attended event

  • confirmed – boolean Indicates whether invitation confirmed they will attend the event

  • specific_occurrence_start – str If invitation is for a specific occurrence of a recurring event, then the start datetime of the event in UTC formatted as yyyy-MM-ddTHH:mm:ss.fffZ

Returns:

dict

Response from PDI in dictionary object