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]¶
- class parsons.newmode.newmode.NewmodeV2(client_id: str | None = None, client_secret: str | None = None, api_version: str = 'v2.1')[source]¶
- 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.
- 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.
- 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.
- 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 The ID of the campaign to retrieve.
params – dict Query parameters to include in the request.
- Returns:
Parsons Table containing campaign data.
- 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 Query parameters to include in the request.
- Returns:
List containing all campaign ids.
- get_recipient(campaign_id: str, street_address: str | None = None, city: str | None = None, postal_code: str | None = None, region: str | None = None, params: dict[str, Any] | None = None, retries: int | None = None) Table[source]¶
Retrieve a specific recipient by ID
- Parameters:
campaign_id – str The ID of the campaign to retrieve.
street_address – str Street address of recipient
city – str City of recipient
postal_code – str Postal code of recipient
region – str Region (i.e. state/province abbreviation) of recipient
params – dict Query parameters to include in the request.
- Returns:
Parsons Table containing recipient data.
- 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 The ID of the campaign to retrieve.
params – dict Query parameters to include in the request.
- Returns:
Parsons Table containing submit data.
- 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 Query parameters to include in the request.
- Returns:
Parsons Table containing submit data.
- class parsons.newmode.newmode.NewmodeV1(api_user: str | None = None, api_password: str | None = None, api_version: str | None = None)[source]¶
- get_tools(params: dict[str, Any] | None = None) Table[source]¶
Get existing tools.
- Parameters:
params – Extra parameters sent to New/Mode library.
- Returns:
Tools information as table.
- get_tool(tool_id: int | str, params: dict[str, Any] | None = None) dict[str, Any] | None[source]¶
Get specific tool.
- Parameters:
tool_id – The id of the tool to return.
params – Extra parameters sent to New/Mode library.
- Returns:
Tool information.
- 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 – The tool to lookup targets.
search – 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.
- Returns:
Targets information as 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 – The id of the tool to return.
params – Extra parameters sent to New/Mode library.
- Returns:
Tool action information.
- 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 – The id of the tool to run.
payload – Payload data used to run the action. Structure will depend on the stuff returned by get_action.
params – Extra parameters sent to New/Mode library.
- Returns:
Action link (if otl) or sid.
- get_target(target_id: int | str, params: dict[str, Any] | None = None) dict[str, Any] | None[source]¶
Get specific target.
- Parameters:
target_id – The id of the target to return.
params – Extra parameters sent to New/Mode library.
- Returns:
Target information.
- get_targets(params: dict[str, Any] | None = None) Table | None[source]¶
Get all targets
- Parameters:
dict (params) – Extra paramaters sent to New/Mode library
- Returns:
Target information
- get_campaigns(params: dict[str, Any] | None = None) Table[source]¶
Get existing campaigns.
- Parameters:
params – Extra parameters sent to New/Mode library.
- Returns:
Campaigns information as table.
- get_campaign(campaign_id: int | str, params: dict[str, Any] | None = None) dict[str, Any] | None[source]¶
Get specific campaign.
- Parameters:
campaign_id – The id of the campaign to return.
params – Extra parameters sent to New/Mode library.
- Returns:
Campaign information.
- get_organizations(params: dict[str, Any] | None = None) Table[source]¶
Get existing organizations.
- Parameters:
params – Extra parameters sent to New/Mode library.
- Returns:
Organizations information as table.
- get_organization(organization_id: int | str, params: dict[str, Any] | None = None) dict[str, Any] | None[source]¶
Get specific organization.
- Parameters:
organization_id – The id of the organization to return.
params – Extra parameters sent to New/Mode library.
- Returns:
Organization information.
- get_services(params: dict[str, Any] | None = None) Table[source]¶
Get existing services.
- Parameters:
params – Extra parameters sent to New/Mode library.
- Returns:
Services information as table.
- get_service(service_id: int | str, params: dict[str, Any] | None = None) dict[str, Any] | None[source]¶
Get specific service.
- Parameters:
service_id – The id of the service to return.
params – Extra parameters sent to New/Mode library.
- Returns:
Service information.