Action Network

Items Version 2

This document describes the OSDI items collection and item resource as implemented by the Action Network.

Items represent the state of being targeted by a specific list (which represents reports or emails in Action Network).

Items are linked to the person resource corresponding to the activist who is targeted by the list.

Items are deduplicated based on person, so any two items in a list will never link to the same person.

Note: Items are read only and the items collection does not return the total_records or total_pages fields, to improve API response speed.

Sections:

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

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/lists/[list_id]/items

Item resources live at endpoints relating to the list they are associated with. The endpoints return a collection of all items associated with that list.

URL Structures:

https://actionnetwork.org/api/v2/lists/[list_id]/items/[item_id]

To address a specific item, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/lists/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/items/167ce1d2-70b7-423e-b480-914981cbeaff

Field names and descriptions

Item 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.
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.
item_type	string	n/a	A property representing the type of resource this item links to. Always 'osdi:person'. Not editable.
action_network:person_id	string	n/a	The native Action Network identifier associated with the person who is associated with this item. Action Network-only feature. System generated, not editable.
action_network:list_id	string	n/a	The native Action Network identifier associated with the list this item is associated with. Action Network-only feature. System generated, not editable.

Links

Link Name	Description
self	A link to this individual item resource.
osdi:person	A link to the person who is associated with this item. Click here for people documentation.
osdi:list	A link to the list this item is associated with. Click here for lists documentation.

Related resources

Lists
People

Scenario: Retrieving a collection of item resources (GET)

Item resources are sometimes presented as collections of items. For example, calling the items endpoint on a specific list will return a collection of all the items associated with that list.

Request

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

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

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


{
  "per_page": 25,
  "page": 1,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items"
    },
    "osdi:items": [
      {
        "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
      },
      {
        "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/a9ccd87c-97f4-48db-9e6b-507509091839"
      },
      //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:items": [
      {
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
          },
          "osdi:list": {
            "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
          }
        },
        "identifiers": [
          "action_network:82e909f9-1ac7-4952-bbd4-b4690a14bec2"
        ],
        "created_date": "2014-03-18T22:25:31Z",
        "modified_date": "2014-03-18T22:25:38Z",
        "item_type": "osdi:person",
        "action_network:person_id": "82e909f9-1ac7-4952-bbd4-b4690a14bec2",
        "action_network:list_id": "71f8feef-61c8-4e6b-9745-ec1d7752f298"
      },
      {
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/a9ccd87c-97f4-48db-9e6b-507509091839"
          },
          "osdi:list": {
            "href": "https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/a9ccd87c-97f4-48db-9e6b-507509091839"
          }
        },
        "identifiers": [
          "action_network:a9ccd87c-97f4-48db-9e6b-507509091839"
        ],
        "created_date": "2014-03-18T22:24:24Z",
        "modified_date": "2014-03-18T22:24:24Z",
        "item_type": "osdi:person",
        "action_network:person_id": "a9ccd87c-97f4-48db-9e6b-507509091839",
        "action_network:list_id": "71f8feef-61c8-4e6b-9745-ec1d7752f298"
      },
      //truncated for brevity
    ]
  }
}

Scenario: Retrieving an individual item resource (GET)

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