Taggings Version 2

This document describes the OSDI taggings collection and tagging resource as implemented by the Action Network.

Taggings represent the state of a person having a certain tag on their record.

Taggings are linked to the person resource corresponding to the activist who is tagged by the associated tag.

Taggings are deduplicated based on person, so any two taggings in a tag will never link to the same person.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/tags/[tag_id]/taggings

Tagging resources live at endpoints relating to the tag they are associated with. The endpoints return a collection of all taggings associated with that tag.

URL Structures:

https://actionnetwork.org/api/v2/tags/[tag_id]/taggings/[tagging_id]

To address a specific item, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/tags/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/taggings/167ce1d2-70b7-423e-b480-914981cbeaff

Back To Top ↑

Field names and descriptions

Tagging fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. Must be globally unique. 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.
item_type string A property representing the type of resource this item links to. Always 'osdi:person' Not editable.
Back To Top ↑

Links

Link Name Description
self A link to this individual tagging resource.
osdi:person A link to the person who is associated with this tagging. Click here for people documentation.
osdi:tag A link to the tag this tagging is associated with. Click here for taggs documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of tagging resources (GET)

Tagging resources are sometimes presented as collections of taggings. For example, calling the taggings endpoint on a specific tag will return a collection of all the taggings associated with that tag.

Request

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

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": 5,
  "per_page": 25,
  "page": 1,
  "total_records": 123,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings"
    },
    "osdi:taggings": [
      {
        "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
      },
      {
        "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings/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:taggings": [
      {
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
          },
          "osdi:tag": {
            "href": "https://actionnetwork.org/api/v2/tags/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"
      },
      {
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings/a9ccd87c-97f4-48db-9e6b-507509091839"
          },
          "osdi:tag": {
            "href": "https://actionnetwork.org/api/v2/tags/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"
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual tagging resource (GET)

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

Request

						
GET https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings/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/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
    },
    "osdi:tag": {
      "href": "https://actionnetwork.org/api/v2/tags/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"
}
Back To Top ↑

Scenario: Creating a new tagging (POST)

You can post a new tagging to a tag with that tag's taggings endpoint and a tagging resource will be created in our system.

When you post a tagging, you can either link to an existing person to register that this person should be tagged with this tag, or you can post taggings as inline arrays when using any of the helper endpoints.

Either way, taggings are deduplicated by person, so a person can only be tagged with a tag once. Posting a new tagging by a person who was previously tagged with that tag will replace the old tagging resource with the new one.

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Here is an example of posting a tagging linking to an existing person:

Request

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

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

{
  "_links" : {
    "osdi:person" : { "href" : "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }
  }
}

Response

						
200 OK

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


{
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/tags/71f8feef-61c8-4e6b-9745-ec1d7752f298/taggings/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
    },
    "osdi:tag": {
      "href": "https://actionnetwork.org/api/v2/tags/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"
}
Back To Top ↑

Scenario: Modifying a tagging (PUT)

Modifying taggings is not allowed via the API. PUT requests will return an error.

Back To Top ↑

Scenario: Deleting a tagging (DELETE)

You can remove a tag from a person's record by deleting the tagging associated with that tag and person.

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Request

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

Header:
api-key:[your api key here]

Response

						
200 OK

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


{
  "notice": "This tagging was successfully deleted."
}
Back To Top ↑