Action Network

Lists Version 2

This document describes the OSDI lists collection and list resource as implemented by the Action Network.

Lists are resources created by the organizer or group associated with your API key. They correspond to reports and emails created in our user interface.

Lists have names (corresponding to our administrative titles), titles, and a description indicating whether they represent an email or report, along with other fields. Activists targeted by the list are represented as items linked to the list, which are themselves linked to the individual people record that item is associated with.

Note: Lists are read only.

Sections:

Endpoints and URL structures
Field names and descriptions
Links
Related resources
Scenario: Retrieving a collection of list resources (GET)
Scenario: Retrieving an individual list resource (GET)
Scenario: POST/PUT/DELETE

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/lists

List resources live exclusively at the above endpoint. The endpoint returns a collection of all the lists associated with your API key.

URL Structures:

https://actionnetwork.org/api/v2/lists/[id]

To address a specific query, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/lists/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3

Field names and descriptions

List fields:

Field Name	Type	Required on POST	Description
identifiers	strings[]	n/a	An array of identifiers in the format `[system name]:[id]`. See the general concepts document for more information about identifiers.
origin_system	string	n/a	A human readable string identifying where this list originated. May be used in the user interface for this purpose.
created_date	datetime	n/a	The date and time the resource was created. System generated, not editable.
modified_date	datetime	n/a	The date and time the resource was last modified. System generated, not editable.
name	string		The list's administrative title, only shown internally and not publicly.
title	string	n/a	The list's name (if it is a report) or subject line (if it is an email).
description	string	n/a	The list's description. System generated, will always be one of ['Email' 'Report'], not editable.
browser_url	string	n/a	The URL to this list's management page on the Action Network.

Links

Link Name	Description
self	A link to this individual list resource.
osdi:items	A link to a collection of all item resources associated with this list. Click here for items documentation.

Related resources

Items

Scenario: Retrieving a collection of list resources (GET)

List resources are sometimes presented as collections of lists. For example, calling the lists endpoint will return a collection of all the lists associated with your API key.

Request

						
GET https://actionnetwork.org/api/v2/lists/

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "total_pages": 10,
  "per_page": 25,
  "page": 1,
  "total_records": 243,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/lists?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/lists"
    },
    "osdi:lists": [
      {
        "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298"
      },
      {
        "href": "https://actionnetwork.org/api/v2/lists/fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "osdi:lists": [
      {
        "identifiers": [
          "action_network:71f8feef-61c8-4e6b-9745-ec1d7752f298"
        ],
        "origin_system": "Action Network",
        "created_date": "2014-03-25T17:11:33Z",
        "modified_date": "2014-03-25T17:13:33Z",
        "title": "Stop Doing The Bad Thing Petition Signers",
        "description": "Report",
        "browser_url": "https://actionnetwork.org/reports/stop-doing-the-bad-thing-petition-signers/manage",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298"
          },
          "osdi:items": {
            "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items"
          }
        }
      },
      {
        "identifiers": [
          "action_network:fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
        ],
        "origin_system": "Action Network",
        "created_date": "2014-03-24T18:26:42Z",
        "modified_date": "2014-03-24T18:27:17Z",
        "title": "Sign our new petition!",
        "description": "Email",
        "browser_url": "https://actionnetwork.org/emails/sign-our-new-petition/manage",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/lists/fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
          },
          "osdi:items": {
            "href": "https://actionnetwork.org/api/v2/lists/fc0a1ec6-5743-4b98-ae0c-cea8766b2212/items"
          }
        }
      },
      //truncated for brevity
    ]
  }
}

Scenario: Retrieving an individual list resource (GET)

Calling an individual list resource will return the resource directly, along with all associated fields and appropriate links to additional information about the list.