Tags Version 2

This document describes the OSDI tags collection and tag resource as implemented by the Action Network.

Tags are resources corresponding to tags created in our user interface for your group to use. They are only available when using group API keys.

Tags have names (corresponding the tag name in our UI) and other fields. Activists with a tag on their record are represented as taggings linked to the tag, which are themselves linked to the individual people record that tagging is associated with.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/tags

Tags resources live exclusively at the above endpoint. The endpoint returns a collection of all the tags associated with your API key. Only group API keys will have tags.

URL Structures:

https://actionnetwork.org/api/v2/tags/[id]

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

Back To Top ↑

Field names and descriptions

Tag fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. See the general concepts document for more information about identifiers.
created_date datetime The date and time the resource was created. System generated, not editable.
modified_date datetime The date and time the resource was last modified. System generated, not editable.
name string Yes The tag's name.
Back To Top ↑

Links

Link Name Description
self A link to this individual tag resource.
osdi:taggings A link to a collection of all tagging resources associated with this tag. Click here for taggings documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of tag resources (GET)

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

Request

						
GET https://actionnetwork.org/api/v2/tags/

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": 10,
  "per_page": 25,
  "page": 1,
  "total_records": 243,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/tags?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/tags"
    },
    "osdi:tags": [
      {
        "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298"
      },
      {
        "href": "https://actionnetwork.org/api/v2/tags/fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
      },
      //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:tags": [
      {
        "identifiers": [
          "action_network:71f8feef-61c8-4e6b-9745-ec1d7752f298"
        ],
        "created_date": "2014-03-25T17:11:33Z",
        "modified_date": "2014-03-25T17:13:33Z",
        "name": "Volunteers",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298"
          },
          "osdi:taggings": {
            "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings"
          }
        }
      },
      {
        "identifiers": [
          "action_network:fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
        ],
        "created_date": "2014-03-24T18:26:42Z",
        "modified_date": "2014-03-24T18:27:17Z",
        "name": "Economic Justice",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/tags/fc0a1ec6-5743-4b98-ae0c-cea8766b2212"
          },
          "osdi:taggings": {
            "href": "https://actionnetwork.org/api/v2/tags/fc0a1ec6-5743-4b98-ae0c-cea8766b2212/taggings"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual tag resource (GET)

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

Request

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

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:71f8feef-61c8-4e6b-9745-ec1d7752f298"
  ],
  "created_date": "2014-03-25T17:11:33Z",
  "modified_date": "2014-03-25T17:13:33Z",
  "name": "Volunteers",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298"
    },
    "osdi:taggings": {
      "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings"
    },
    "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: Creating a new tag (POST)

You can post a new tags via the tags endpoint and a tag resource will be created in our system.

Tags are deduplicated by name. Posting a tag with the same name as an existing tag will redirect to that tag's existing resource.

Here is an example of posting a tag:

Request

						
POST https://actionnetwork.org/api/v2/tags/

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "name": "Volunteers"
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:71f8feef-61c8-4e6b-9745-ec1d7752f298"
  ],
  "created_date": "2014-03-25T17:11:33Z",
  "modified_date": "2014-03-25T17:13:33Z",
  "name": "Volunteers",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298"
    },
    "osdi:taggings": {
      "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings"
    },
    "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: PUT/DELETE

Putting and deleting tags is not allowed. Attempts will result in errors.

Back To Top ↑