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

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

Back To Top ↑

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

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

Related resources

Back To Top ↑

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

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.

Request

						
GET https://actionnetwork.org/api/v2/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/82e909f9-1ac7-4952-bbd4-b4690a14bec2

Header:
OSDI-API-Token: your_api_key_here
					

Response

						
200 OK

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


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

Scenario: POST/PUT/DELETE

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

Back To Top ↑