New/Mode¶

Overview¶

New/Mode is a multi-channel advocacy and civic engagement platform for organizations and campaigns. This Parsons class includes methods for fetching tools, actions, targets, campaigns, organizations, services, and outreaches. There are also methods for looking up targets and running actions given a tool_id. Most methods return either individual items as dictionaries or lists of items as Parsons Table objects.

Note

Authentication: To use the class, you need to provide a New/Mode username and password. For more information, see The New/Mode API is Here.

Quick Start¶

To instantiate the Newmode class, you can either store your New/Mode username and password as environmental variables (NEWMODE_API_USER and NEWMODE_API_PASSWORD, respectively) or pass in your username and password as arguments:

from parsons import Newmode

# instantiate with API credentials stored as environmental variables
newmode = Newmode()

# instantiate with API credentials passed as arguments
newmode = Newmode(api_user='my_username', api_password='my_password')

# Get existing tools.
tools = newmode.get_tools()

# Get specific tool.
tool = newmode.get_tool(tool_id)

API¶

class parsons.newmode.newmode.Newmode(client_id: str | None = None, client_secret: str | None = None, api_user: str | None = None, api_password: str | None = None, api_version: str = 'v1.0')[source]¶

Parameters:

client_id (str | None)
client_secret (str | None)
api_user (str | None)
api_password (str | None)
api_version (str)

Return type:

NewmodeV1 | NewmodeV2

class parsons.newmode.newmode.NewmodeV2(client_id: str | None = None, client_secret: str | None = None, api_version: str = 'v2.1')[source]¶

Parameters:

client_id (str | None)
client_secret (str | None)
api_version (str)

base_request(method: str, url: str, retries: int = 2, use_campaigns_client: bool = False, data: dict[str, Any] | None = None, json: dict[str, Any] | None = None, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Internal method to instantiate OAuth2APIConnector class, make a single call to Newmode API, and validate the response.

Parameters:

method (str)
url (str)
retries (int)
use_campaigns_client (bool)
data (dict[str, Any] | None)
json (dict[str, Any] | None)
params (dict[str, Any] | None)

Return type:

dict[str, Any] | None

paginate_request(method: str, endpoint: str, use_campaigns_client: bool = False, data_key: str = 'data', data: dict[str, Any] | None = None, json: dict[str, Any] | None = None, params: dict[str, Any] | None = None, supports_version: bool = True, override_api_version: str | None = None, retries: int = 2) → list[dict[str, Any]][source]¶

Wrapper method to handle pagination for API requests.

Parameters:

method (str)
endpoint (str)
use_campaigns_client (bool)
data_key (str)
data (dict[str, Any] | None)
json (dict[str, Any] | None)
params (dict[str, Any] | None)
supports_version (bool)
override_api_version (str | None)
retries (int)

Return type:

list[dict[str, Any]]

converted_request(endpoint: str, method: str, retries: int = 2, supports_version: bool = True, data: dict[str, Any] | None = None, json: dict[str, Any] | None = None, params: dict[str, Any] | None = None, convert_to_table: bool = True, data_key: str | None = None, use_campaigns_client: bool = False, override_api_version: str | None = None) → Table | dict[str, Any][source]¶

Internal method to make a call to the Newmode API and convert the result to a Parsons table.

Parameters:

endpoint (str)
method (str)
retries (int)
supports_version (bool)
data (dict[str, Any] | None)
json (dict[str, Any] | None)
params (dict[str, Any] | None)
convert_to_table (bool)
data_key (str | None)
use_campaigns_client (bool)
override_api_version (str | None)

Return type:

Table | dict[str, Any]

get_campaign(campaign_id: str, retries: int = 2, params: dict[str, Any] | None = None) → Table[source]¶

Retrieve a specific campaign by ID.

In v2, a campaign is equivalent to Tools or Actions in V1.

Parameters:

campaign_id (str) – str The ID of the campaign to retrieve.
params (dict[str, Any] | None) – dict Query parameters to include in the request.
retries (int)

Returns:

Parsons Table containing campaign data.

Return type:

Table

get_campaign_ids(retries: int = 2, params: dict[str, Any] | None = None) → list[str][source]¶

Retrieve all campaigns In v2, a campaign is equivalent to Tools or Actions in V1.

Parameters:

organization_id – str ID of organization
params (dict[str, Any] | None) – dict Query parameters to include in the request.
retries (int)

Returns:

List containing all campaign ids.

Return type:

list[str]

Retrieve a specific recipient by ID

Parameters:

campaign_id (str) – str The ID of the campaign to retrieve.
street_address (str | None) – str Street address of recipient
city (str | None) – str City of recipient
postal_code (str | None) – str Postal code of recipient
region (str | None) – str Region (i.e. state/province abbreviation) of recipient
params (dict[str, Any] | None) – dict Query parameters to include in the request.
retries (int | None)

Returns:

Parsons Table containing recipient data.

Return type:

Table

run_submit(campaign_id: str, retries: int = 2, json: dict[str, Any] | None = None, data: dict[str, Any] | None = None, params: dict[str, Any] | None = None) → dict[str, Any][source]¶

Pass a submission from a supporter to a campaign that ultimately fills in a petition, sends an email or triggers a phone call depending on your campaign type

Parameters:

campaign_id (str) – str The ID of the campaign to retrieve.
params (dict[str, Any] | None) – dict Query parameters to include in the request.
retries (int)
json (dict[str, Any] | None)
data (dict[str, Any] | None)

Returns:

Parsons Table containing submit data.

Return type:

dict[str, Any]

get_submissions(campaign_id: str, retries: int = 2, params: dict[str, Any] | None = None) → Table[source]¶

Retrieve and sort submissions and contact data for a specified campaign using a range of filters that include campaign id, data range and submission status

Parameters:

params (dict[str, Any] | None) – dict Query parameters to include in the request.
campaign_id (str)
retries (int)

Returns:

Parsons Table containing submit data.

Return type:

Table

class parsons.newmode.newmode.NewmodeV1(api_user: str | None = None, api_password: str | None = None, api_version: str | None = None)[source]¶

Parameters:

api_user (str | None)
api_password (str | None)
api_version (str | None)

get_tools(params: dict[str, Any] | None = None) → Table[source]¶

Get existing tools.

Parameters:: params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.
Returns:: Tools information as table.
Return type:: Table

get_tool(tool_id: int | str, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Get specific tool.

Parameters:

tool_id (int | str) – The id of the tool to return.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Tool information.

Return type:

dict[str, Any] | None

lookup_targets(tool_id: int | str, search: str | None = None, params: dict[str, Any] | None = None) → Table[source]¶

Lookup targets for a given tool

Parameters:

tool_id (int | str) – The tool to lookup targets.
search (str | None) – The search criteria. It could be: - Empty: If empty, return custom targets associated to the tool. - Postal code: Return targets matched by postal code. - Lat/Long: Latitude and Longitude pair separated by ‘::’. Ex. 45.451596::-73.59912099999997. It will return targets matched for those coordinates. - Search term: For your csv tools, this will return targets matched by given valid search term.
params (dict[str, Any] | None)

Returns:

Targets information as table.

Return type:

Table

get_action(tool_id: int | str, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Get the action information for a given tool.

Parameters:

tool_id (int | str) – The id of the tool to return.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Tool action information.

Return type:

dict[str, Any] | None

run_action(tool_id: int | str, payload: dict[str, Any], params: dict[str, Any] | None = None) → str | int | None[source]¶

Run specific action with given payload.

Parameters:

tool_id (int | str) – The id of the tool to run.
payload (dict[str, Any]) – Payload data used to run the action. Structure will depend on the stuff returned by get_action.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Action link (if otl) or sid.

Return type:

str | int | None

get_target(target_id: int | str, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Get specific target.

Parameters:

target_id (int | str) – The id of the target to return.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Target information.

Return type:

dict[str, Any] | None

get_targets(params: dict[str, Any] | None = None) → Table | None[source]¶

Get all targets

Parameters:

dict (params) – Extra paramaters sent to New/Mode library
params (dict[str, Any] | None)

Returns:

Target information

Return type:

Table | None

get_campaigns(params: dict[str, Any] | None = None) → Table[source]¶

Get existing campaigns.

Parameters:: params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.
Returns:: Campaigns information as table.
Return type:: Table

get_campaign(campaign_id: int | str, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Get specific campaign.

Parameters:

campaign_id (int | str) – The id of the campaign to return.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Campaign information.

Return type:

dict[str, Any] | None

get_organizations(params: dict[str, Any] | None = None) → Table[source]¶

Get existing organizations.

Parameters:: params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.
Returns:: Organizations information as table.
Return type:: Table

get_organization(organization_id: int | str, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Get specific organization.

Parameters:

organization_id (int | str) – The id of the organization to return.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Organization information.

Return type:

dict[str, Any] | None

get_services(params: dict[str, Any] | None = None) → Table[source]¶

Get existing services.

Parameters:: params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.
Returns:: Services information as table.
Return type:: Table

get_service(service_id: int | str, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Get specific service.

Parameters:

service_id (int | str) – The id of the service to return.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Service information.

Return type:

dict[str, Any] | None

get_outreaches(tool_id: int | str, params: dict[str, Any] | None = None) → Table[source]¶

Get existing outreaches for a given tool.

Parameters:

tool_id (int | str) – Tool to return outreaches.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Outreaches information as table.

Return type:

Table

get_outreach(outreach_id: int | str, params: dict[str, Any] | None = None) → dict[str, Any] | None[source]¶

Get specific outreach.

Parameters:

outreach_id (int | str) – The id of the outreach to return.
params (dict[str, Any] | None) – Extra parameters sent to New/Mode library.

Returns:

Outreach information.

Return type:

dict[str, Any] | None