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.
- Versions and what's new
- Technical considerations
- Getting started
- Tools and browsing the API
- Tutorials: Making your first calls
- Suggestions for speed and efficiency
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_recordsfields 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_datefirst 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
subscribedstatus was valid. Now,
unsubscribedare valid. If a person is new and no status or the
subscribedstatus is passed, the person will be subscribed. If the person is new and
unsubscribedis 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
subscribedstatus in this last situation will travel up the network, so the person will be resubscribed at each level. An
unsubscribedstatus will not.) Other helpers for actions continue to work as they did, with
subscribedbeing the only valid status.
- Added a
languages_spokenarray to people on the API, indicating their preferred language.
- Added a read-only
action_network:hiddenfield 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_itemsfield from /lists API endpoints, as they were slow.
March 26, 2016:
- 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:signaturesendpoint from the
fundraising_pagesendpoint and added the correct
attendancesin 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
- 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.
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.
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.
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.
API keys must be sent as a header in this format:
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.
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.
- Get a list of activists on to your email list
- Get a list of events created by your account
- Get a list of people who signed one of your petitions
- Get the embed code for a form you created
- Add people to your email list
- Post a new fundraising page from another system and add donors to that page and your list
- Add signatures to a petition via a custom form, with an email autoresponse
- Unsubscribe people from your list
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.