The Action Network API -- Getting Started Version 2

The Action Network API allows organizers with Action Network accounts and, in most cases, API keys to interact with the Action Network system. The API supports use cases such as syncing online organizing data (people, email addresses, action histories) with other systems, migrating data between systems, managing subscriptions, pulling embed code for actions into CMS systems, creating your own forms to send in activist data, and similar functions.

The API is not intended to enable the creation of a replacement user interface.

Version 2 of our API has arrived! Check out what's new below.

Sections:

Versions and what's new

The Action Network API is currently in Version 2. Version 1 is depreciated and no longer supported. It will still work, but will not receive future enhancements or fixes. You can find Version 1 documentation here.

Version 2 updates the Action Network API to version 1.1.1 of the OSDI specification, and specifically implements and changes a few key things:

September 2, 2016:

  • Removed the total_pages and total_records fields from the people collection on GET to improve speed.
  • A next link will be present if the page in the collection is the last page, but not present if no resources are returned (ie. you've gone past the last page), to improve speed.
  • People are no longer ordered by newest modified_date first in the people collection on GET, to improve speed.

August 22, 2016:

  • Updated how subscription status works on the person signup helper. Previously, only the subscribed status was valid. Now, subscribed and unsubscribed are valid. If a person is new and no status or the subscribed status is passed, the person will be subscribed. If the person is new and unsubscribed is passed, they will be added to the list unsubscribed. If the person is not new and no status is passed, their subscription status will not be changed. If status is passed, the person's status will be changed. (In networks, a subscribed status in this last situation will travel up the network, so the person will be resubscribed at each level. An unsubscribed status will not.) Other helpers for actions continue to work as they did, with subscribed being the only valid status.
  • Added a languages_spoken array to people on the API, indicating their preferred language.
  • Added a read-only action_network:hidden field to action resources (petitions, forms, etc...) on the API, indicating whether the action is hidden in our UI or not.

April 21, 2016:

  • Removed the total_items field from /lists API endpoints, as they were slow.

March 26, 2016:

  • API action helper endpoints (such as the record signatures helper) can be POSTed to without an API key, returning success or failure but no other data. This allows you to use our API via javascript without fear, since no API keys will be leaked to browsers.
  • You can also optionally add an autoresponse trigger to your helper POSTs, which will trigger an autoresponse email based on the settings of the page you're POSTing to. For example, if you're POSTing to a petition that has the autoresponse email turned on and you include the autoresponse trigger, the activist will get an autoresponse email as normal, thanking them for taking action. If you're POSTing to a page with the autoresponse turned off, they won't get that email.
  • To go along with this, OSDI has released a jQuery plugin, allowing you to easily use unauthenticated POST and triggers in-browser. Check it out here.
  • Action API endpoints (/petitions, /forms, etc...) also return a URL to the featured banner image, if the action has one.
  • We've removed the non-working osdi:signatures endpoint from the fundraising_pages endpoint and added the correct osdi:person endpoint on attendances in addition to the incorrect osdi:people, which will be removed in the next API version upgrade.

December 8, 2015:

  • A new header is used for authentication instead of api-key -- instead, please use OSDI-API-Token.
  • Questions and question answers have been removed. Custom fields are now expressed as inline object hashes on each person record, simplifying retrieving and working with custom fields.
  • Tags and taggings endpoints have been added, allowing you to view, add, and remove tag data on people.
  • Advocacy campaign and outreach endpoints have been added, which correspond to our letter campaigns tool, allowing you to view, add, and modify these resources.
  • Queries have been renamed lists, with similar functionality.
  • Attendance has been renamed to attendances, modified_at and created_at to modified_date and created_date, originating_system to origin_system, url to browser_url, and other small naming changes.
  • Administrative titles are now available on the api as name fields, and summary has moved to the title field.
  • The API now returns all people on your email list, whether they are subscribed or not. A status field indicates their subscription status. Changing that status field will subscribe or unsubscribe them from your list.
  • POSTing (either to helpers or not) will now respect subscription status. If the person you post is new to your list, they will be subscribed. If not, their subscription status will not change. If you are using helpers, if you pass a subscribed value for status, we will subscribe that person.
  • The OSDI person signup helper has been implemented, allowing you to add people to your list directly.
  • More embed options have been added to embed endpoints, reflecting the full range of widget types available.
  • The modified_date on person records now updates any time a person takes an action, allowing for easier syncing of action history via oData queries.
  • Every endpoint has been updated to conform to the latest OSDI standard, 1.1.0, with some minor field name changes as well as functionality updates.

Technical considerations

The Action Network API is served in HAL+JSON format. It generally conforms to the Open Supporter Data Interface (OSDI) specification version 1.0.2, which can be found at opensupporter.org.

HAL provides links to make navigation between endpoints and resources easy. In addition, the API is curied, linking directly to documentation within API calls.

The Content-Type: application/json header is generally required when making requests to the API.

We rate limit the API to a maximum of 4 calls per second.

Getting started

API entry point (AEP) is https://actionnetwork.org/api/v2

An API key is required to access most of the API. API keys are considered a partner feature. Please contact us to become a partner. Each user account and group on the Action Network has a separate API key allowing you to access that user or group's data.

Once you've been given access to our API, you can generate your key from the API & Sync page, located in the "Start Organizing" menu, in the right column. Once on the page, first choose the list you want to generate a key for. Choosing your personal list will allow you to add actions and people to your personal account's email list. Choosing any groups you are an administrator of allows you to add actions or people to that group's list. After you select the list, you can generate an API key for that list.

You can revoke your key and regenerate a new one from the API & Sync page.

Note: Keep your API key secret. Anyone with your API key will be able to access any data in your account. Therefore, large parts of the Action Network API are not suitable for front end-only implementations (such as a javascript client), as this could expose your API key to others. However, some endpoints allow POSTed data without an API key, making them suitable for javascript implementations.

API keys must be sent as a header in this format:

            
OSDI-API-Token: your_api_key_here
            
          

Some portions of the API are accessible without a key. Specifically, we allow posting of data using the helper endpoints without an API key, allowing for javascript implementations where leaking an API key to a user's browser would be unacceptable. See the helper documentation for specifics and examples, or the blind POST and autoresponse tutorial.

Tools and browsing the API

Once you have your API key, you can try the API using our browser here. Make sure to enter your API key to acces your data.

The browser is extremely useful for getting a feel for how the Action Network API works. It supports GET, POST, PUT and other operations. It is based off of Mike Kelly's HAL browser -- you can read more about it here.

OSDI has also released a jQuery plugin, which works with our unauthenticated POST and autoresponse trigger features, allowing you to create forms and send in responses over the API using javascript running in a user's browser. Check it out here.

Tutorials: Making your first calls

Once you have an API key, it's time to make your first calls. We've put together a few tutorial scenarios to help you understand what the API can do.

Or, dive right into the full documentation here.

Suggestions for speed and efficiency

We have a few suggestions to ensure speed and efficiency when using the API:

  • Avoid big collections where possible, as they are sometimes slow and will often require lots of calls via paging.
  • Make use of oData modified_date queries to only retrieve new records from collections since your last run through the API.
  • Because calls slow down the farther down in pages you go (ex: page 10 will be much faster to retrieve than page 10,000), prefer to retrieve records from the API more often rather than less often to limit the number of pages you'll need to go through. For example, run your code to pull newly modified records every hour rather than every day.