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

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

Back To Top ↑

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

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

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

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.

Request

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

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

Scenario: POST/PUT/DELETE

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

Back To Top ↑