Queries Version 2

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

Queries are created by a group associated with your API key and are saved sets of parameters that are used for targeting email or reports. For example, a query could target activists on your group's list who live in New York OR have taken action in the last 30 days.

Queries have names and a URL pointing to their editing page in the Action Network UI as well as other metadata like when they were created.

Note: Queries are read only.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/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/v2/queries/[id]

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

Back To Top ↑

Field names and descriptions

Query 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 query 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 n/a The query's name, only shown internally and not publicly.
browser_url string n/a The URL to this query's editing page on the Action Network.
Back To Top ↑

Links

Link Name Description
self A link to this individual query resource.
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/v2/queries/

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": 7,
  "per_page": 25,
  "page": 1,
  "total_records": 162,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/queries?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/queries"
    },
    "osdi:queries": [
      {
        "href": "https://actionnetwork.org/api/v2/queries/a4dde5b6-0512-48ea-b4ad-63a71117b43d"
      },
      {
        "href": "https://actionnetwork.org/api/v2/queries/a27178b9-45c3-4844-8ebf-ebd5da74a1e3"
      },
      //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:queries": [
      {
        "identifiers": [
          "action_network:a4dde5b6-0512-48ea-b4ad-63a71117b43d"
        ],
        "origin_system": "Action Network",
        "created_date": "2014-03-24T18:03:45Z",
        "modified_date": "2014-03-25T15:00:22Z",
        "name": "All donors",
        "browser_url": "https://actionnetwork.org/queries/1/edit",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/queries/a4dde5b6-0512-48ea-b4ad-63a71117b43d"
          }
        }
      },
      {
        "identifiers": [
          "action_network:a27178b9-45c3-4844-8ebf-ebd5da74a1e3"
        ],
        "origin_system": "Action Network",
        "created_date": "2014-03-14T15:21:05Z",
        "modified_date": "2014-03-17T19:56:11Z",
        "name": "Volunteer prospects",
        "browser_url": "https://actionnetwork.org/queries/2/edit",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/queries/a27178b9-45c3-4844-8ebf-ebd5da74a1e3"
          }
        }
      },
      //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/v2/queries/a4dde5b6-0512-48ea-b4ad-63a71117b43d

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:a4dde5b6-0512-48ea-b4ad-63a71117b43d"
  ],
  "origin_system": "Action Network",
  "created_date": "2014-03-24T18:03:45Z",
  "modified_date": "2014-03-25T15:00:22Z",
  "name": "All donors",
  "browser_url": "https://actionnetwork.org/queries/1/edit",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/queries/a4dde5b6-0512-48ea-b4ad-63a71117b43d"
    },
    "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 queries is not allowed. Attempts will result in errors.

Back To Top ↑