Action Network

Queries Version 1

Note: This documentation describes Version 1 of our API, which is now depreciated. It will continue to work, but it will not reveive any updates or bug fixes. We recommend you use Version 2 instead. In Version 2, queries have been replaced by lists, with similar functionality. Documentation for lists for Version 2 of our API is available here.

This document describes the OSDI queries collection and query resource as implemented by the Action Network.

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

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

Note: Queries are read only.

Sections:

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

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v1/queries

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

URL Structures:

https://actionnetwork.org/api/v1/queries/[id]

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

Field names and descriptions

Field Name	Type	Required on POST	Description
identifiers	array[]	n/a	An array of identifiers in the format `[system name]:[id]`. See the general concepts document for more information about identifiers.
originating_system	string	n/a	A human readable string identifying where this query originated. May be used in the user interface for this purpose.
created_at	datetime	n/a	The date and time the resource was created. System generated, not editable.
modified_at	datetime	n/a	The date and time the resource was last modified. System generated, not editable.
summary	string	n/a	The query's name (if it is a report) or subject line (if it is an email).
description	string	n/a	The query's description. System generated, will always be one of ["Email" "Report"], not editable.
url	string	n/a	The URL to this query's management page on the Action Network.
total_items	integer	n/a	A system generated count of the number of items targeted by this query. Not editable.
dynamic	boolean	n/a	An indication of whether this query will return a list of items currently matching the underlying targeting options (the true state) or whether it will return a list of items targeted when the query was saved (the false state). System generated, always false, not editable.

Links

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

Scenario: Retrieving a collection of query resources (GET)

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

Request

						
GET https://actionnetwork.org/api/v1/queries/

Header:
api-key:[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/v1/queries?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v1/queries"
    },
    "osdi:queries": [
      {
        "href": "https://actionnetwork.org/api/v1/queries/71f8feef-61c8-4e6b-9745-ec1d7752f298"
      },
      {
        "href": "https://actionnetwork.org/api/v1/queries/fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "osdi:queries": [
      {
        "identifiers": [
          "action_network:71f8feef-61c8-4e6b-9745-ec1d7752f298"
        ],
        "originating_system": "Action Network",
        "created_at": "2014-03-25T17:11:33Z",
        "modified_at": "2014-03-25T17:13:33Z",
        "summary": "Stop Doing The Bad Thing Petition Signers",
        "description": "Report",
        "url": "https://actionnetwork.org/reports/stop-doing-the-bad-thing-petition-signers/manage",
        "total_items": 2394,
        "dynamic": false,
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/queries/71f8feef-61c8-4e6b-9745-ec1d7752f298"
          },
          "osdi:items": {
            "href": "https://actionnetwork.org/api/v1/queries/71f8feef-61c8-4e6b-9745-ec1d7752f298/items"
          }
        }
      },
      {
        "identifiers": [
          "action_network:fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
        ],
        "originating_system": "Action Network",
        "created_at": "2014-03-24T18:26:42Z",
        "modified_at": "2014-03-24T18:27:17Z",
        "summary": "Sign our new petition!",
        "description": "Email",
        "url": "https://actionnetwork.org/emails/sign-our-new-petition/manage",
        "total_items": 3625,
        "dynamic": false,
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/queries/fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
          },
          "osdi:items": {
            "href": "https://actionnetwork.org/api/v1/queries/fc0a1ec6-5743-4b98-ae0c-cea8766b2212/items"
          }
        }
      },
      //truncated for brevity
    ]
  }
}

Scenario: Retrieving an individual query resource (GET)

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