1. New/Mode Knowledge Base
  2. Advocacy Action In-Depth Guides

Using the New/Mode API

Our API gives you a different way to use your campaign data, from getting supporter details and action metrics to automating submissions.

This article covers:

- What is the New/Mode API?

- API Authentication

- API Resources / Endpoints

- API Example Uses: automate submissions, get submission data for an action, get data for a submission, get data about a target

- Interactive API Documentation

What is the New/Mode API?

Our API is a way for you to interact with the data associated with your New/Mode organization without using the New/Mode platform.

Developers within your organization can use it to get data about your organization, your campaigns, your actions, and any CRMs and analytics services tied to your organization. It can also be used to look up targets and interact with your actions.

The New/Mode API is a fully RESTful API, OSDI compliant where possible, and can provide responses in HAL/JSON or JSON formats.

  

API Authentication

To use our API you'll need to authenticate in two steps:

1. Basic Authentication: providing your New/Mode username (email address) and password

2. CSFR token: providing a unique token that's automatically generated after the initial authentication.

Here's an example of what authenticating with basic authentication and then getting a token to use for future requests looks like:

curl -c cookie.txt --user USER:PASSWORD
https://engage.newmode.net/api/login

Conveniently the authentication above takes care of both steps, but if you ever need to get a token after completing basic authentication you can do so with something like:

curl -b cookie.txt https://engage.newmode.net/api/session/token

Which would return something along the lines of:

{"X-CSRF-Token":"jsDIw..........k"}

API Resources / Endpoints

  • Organization
    At /api/organization you can see all information relating to your organization, as well as a list of campaign IDs belonging to your organization.
  • Campaign
    At /api/campaign you can see all information relating to your campaigns, as well as a list of action IDs under each campaign.
  • Tool
    At /api/tool you can see all information relating to your actions.
  • Service
    At /api/service you can see all information relating to your integrations with CRMs and Analytics services.
  • Lookup
    At /api/lookup you can perform a target lookup against one of your actions using either a postal code, an address, or custom search criteria.
  • Target
    At /api/target you can retrieve all information about a specific target. Using this in combination with the lookup resource means you can get a list of appropriate targets and then get the extra information you need about them.
  • Action
    At /api/action you can use GET to pull a list of the fields on a specific action, and use PATCH to automatically create a submission on an action by passing all the supporter data that's usually entered in the front-end in the request body.
    • If the action is an email action then all emails are immediately sent.
    • If the action is a call action then a call is automatically triggered.
    • If the action is a fax action then all faxes are immediately sent.
    • If the action is a tweet action then a one-time link is returned which can be used by a user logged into Twitter to complete the action.
  • Submissions / Outreaches
    At /api/outreach you can retrieve a paginated list of submissions received by a specific action in the OSDI compliant format for “outreach”.

    You can pull submission data like first name, last name, email address, phone number, postal/zip/address, message sent, representatives contacted, political districts contacted, GDPR opt-ins, call durations, etc.

API Example uses

Automate submissions

You can use the /api/action endpoint to make submissions on behalf of a list of supporters.

1. Start by getting your action's ID number, which you can see in the URL bar of your browser when editing the action:

2. Make a GET request to obtain a list of the fields that are on the actions, because that's the supporter data you'll need to send over to make the submissions.

This request would look something like the code below, with "123" being your action's ID number:
curl -X GET -H "X-CSRF-Token: jsDIw..........k" -b cookie.txt
https://engage.newmode.net/api/action/123
3. Knowing which fields need to be filled, pass those details through the API using a PATCH request like the one below.

<Payload> should be replaced with your JSON encoded payload containing at least all the mandatory fields required to trigger your action.
curl -X PATCH -H "X-CSRF-Token: jsDIw..........k" -H "Content Type:
application/json" -d '<payload>' -b
cookie.txt https://engage.newmode.net/api/action/123

Get submission data for an action

You can use the /api/outreach endpoint to get submission data for a specific action. You can then use this data to populate your CRM or a mailing list if there's no direct integration available.

First, get your action's ID number, which you can see in the URL bar of your browser when editing the action:


With that information, send a request like the one below to get a paginated list of submissions for action 123 (by default, each page has data from 50 submissions).

curl -H "X-CSRF-Token: jsDIw..........k" -b cookie.txt
https://engage.newmode.net/api/outreach?nid=123

Get data for a submission

You can use the /api/outreach endpoint to get data for a specific submission within an action.

First, get the submission's ID (SID), which you can see listed on the Submissions page or in the URL bar of your browser when looking at the submission:

Next send a request like the one below, with the submission ID after /outreach/ (SID is "456" in this example):

curl -H "X-CSRF-Token: jsDIw..........k" -b cookie.txt
https://engage.newmode.net/api/outreach/456

Get data about a target

Start by creating an action as you would normally, adding the dataset(s) you're interested in as location-based targets to it, and selecting a postal code or address field.
Make a note of your new action's ID number, which you can see in the URL bar of your browser when editing the action:

You can then use the /api/lookup endpoint to send an address or a postal code to your action through our API to look up the target(s) for that location.
If you want to get more details about a specific target you can use the /api/target endpoint next to get everything we have in our database for them.
 

Interactive API documentation

If you'd like to get a feel for how our API works, take a look at our interactive documentation here. After authenticating, you can try the different endpoints and see what kind of data you can get from each one.

Authenticating

1. Open the New/Mode API documentation page, and click on the 'Authorize' button on the right side:

2. In the Available Authorizations window, enter the email and password that you use to log into your New/Mode account and click on 'Authorize'. Once you see that your credentials have been added, close the window.

3. Click on the GET method under 'anonymous-user' to expand it, then the 'Try it out' button, and then click the 'Execute' button.

4. Under the Responses header, copy the randomly generated cookie. You can manually copy only the cookie on the fourth line after "Basic" (leaving out the ' mark at the end), or use the copy icon to copy the entire snippet, paste it somewhere, and copy only the cookie.

5. Once you have the cookie copied, scroll up a bit and click on the 'Authorize' button again. Paste the cookie into the 'Value' field, click on 'Authorize', then close the window.

6. Now that you're fully authenticated, you can use all the options under 'authenticated-user' :)

 

 


Last updated: May 17, 2023