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

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

Back To Top ↑

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.
Back To Top ↑

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.
Back To Top ↑

Related resources

Back To Top ↑

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
    ]
  }
}
					
Back To Top ↑

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.

Request

						
GET https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298

Header:
OSDI-API-Token: your_api_key_here
					

Response

						
200 OK

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


{
  "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"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
					
Back To Top ↑

Scenario: POST/PUT/DELETE

Posting, putting, and deleting lists is not allowed. Attempts will result in errors.

Back To Top ↑