Taggings

Taggings let you store or gather essential details on your entities and connections. Taggings reflect the info fields and responses attached to an entity or connection in the Action Builder UI. They represent the state of an entity or connection having a certain tag on their record.

Taggings can be applied to people or connections.

Taggings can be used to store additional information on a entity or connection in various formats, including standard, number, date, addresss, note, and shift.

Endpoints and URL Structures
Field Names and Descriptions
Links
Related Resources
Scenario: Retrieving a Collection of Taggings Resources (GET)
Scenario: Retrieving an Individual Tagging Resource (GET)
Scenario: POST/PUT
Scenario: Deleting an Individual Tagging Resource (DELETE)

Endpoints and URL Structures


https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/tags/[tag_id]/taggings

https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/people/[person_id]/taggings

https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/connections/[connection_id]/taggings

Tagging resources live at the above endpoints. The endpoint returns a collection of all the taggings associated with your API key and specified campaign and person, connection, or tag.

URL Structures:


https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/tags/[tag_id]/taggings/[tagging_id]

To address a specific tagging, use the resource type name like:


https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/0e51a7e5-321c-4d39-b216-31a57f04e5f4/taggings/37036c91-cfaa-4704-a891-3c2c1ded0bd4

Field Names and Descriptions

Tagging Fields

Field Name	Type	Required on POST	Description
origin_system	string		A human readable string identifying where this tagging originated.
identifiers	strings[]		An array containing the read-only Action Builder identifier of this resource 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.
item_type	string		A property representing the type of resource this tagging links to (ex: osdi:people, action_builder:connections).
action_builder:section	string	Yes	The section this tag belongs to.
action_builder:field	string	Yes	The name of the field, corresponds to field on the UI.
action_builder:field_type	flexnum		The data type for the field. One of 'standard', 'number', 'date', 'address', 'note', or 'shift'.
name	string	Yes	The response name for this field.
action_builder:create_tag	boolean		Whether to create a response with this response name if it does not already exist. Only valid when used with the person signup helper or connection helper
action_builder:number_response	integer		The response for a number type field. Will only be present for these types of fields.
action_builder:date_response	datetime		The response for a date type field. Will only be present for these types of fields.
action_builder:postal_address_response	postal_address		The response for a address type field. Will only be present for these types of fields.
action_builder:note_response	string		The response for a note type field. Will only be present for these types of fields.
action_builder:shift_response	shift_response[]		The array of responses for a shift type field. Will only be present for these types of fields.
action_builder:timezone	string		The timezone for the shift. Only present when the type of field is shift.

Postal Addresses Fields

Field Name	Type	Description
postal_addresses.address_lines	string[]	An array of strings representing the tagging's street address. There can be a maximum two items in the array, equating to two address lines.
postal_addresses.locality	string	A city or other local administrative area.
postal_addresses.region	string	The state or region represented by the two digit abbreviation. Only supports US and Canada.
postal_addresses.postal_code	string	The region specific postal code, such as a zip code.
postal_addresses.country	string	The country code according to ISO 3166-1 Alpha-2. Only supports `US` or `CA`.
postal_addresses.source	string	The origin of this postal address. System generated, not editable.

Shift Response Fields

Field Name	Type	Description
shift_response.day	string	The day of the week for the shift.
shift_response.start_time	string	The start time for the shift in 24-hour format.
shift_response.end_time	string	The end time for the shift in 24-hour format.

Links

Link Name	Description
self	A link to this individual tagging resource.
action_builder:campaign	A link to the campaign this tagging is in. Click here for campaigns documentation.
osdi:tags	A link to the tag associated with this tagging. Click here for tags documentation.
osdi:people	A link to the people or entities forming this tagging. Click here for taggings documentation.
osdi:taggings	A link to the tagging. Click here for taggings documentation.

Related Resources

Scenario: Retrieving a collection of taggings resources (GET)

Taggings resources are sometimes presented as collections of taggings. For example, calling the taggings endpoint will return a collection of all the taggings associated with that API key and specified campaign and tag.

Request

						
GET https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/0e51a7e5-321c-4d39-b216-31a57f04e5f4/taggings		

Header:
OSDI-API-Token: your_api_key_here

Response

						
{
  "per_page": 25,
  "page": 1,
  "total_pages": 1,
  "_embedded": {
    "osdi:taggings": [
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:f002be4c-4d9f-4dc8-b858-6c27bf036929"
        ],
        "created_date": "2022-02-22T20:13:35.767Z",
        "modified_date": "2022-02-22T20:13:35.767Z",
        "item_type": "entity",
        "action_builder:section": "Basic Info",
        "action_builder:field": "Meeting Place",
        "action_builder:field_type": "address",
        "name": "1900 L St",
        "action_builder:postal_address_response": {
          "address_lines": [
            "1900 L St NW"
          ],
          "locality": "Washington",
          "region": "DC",
          "postal_code": "20036",
          "country": "US"
        },
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/f002be4c-4d9f-4dc8-b858-6c27bf036929"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "osdi:tag": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/e5b603ec-1ddc-45d3-ace2-6088006e2f39"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:3c850f2c-8af5-4aae-9627-1faf11a98671"
        ],
        "created_date": "2022-02-18T16:55:34.762Z",
        "modified_date": "2022-02-18T16:55:34.762Z",
        "item_type": "entity",
        "action_builder:section": "Basic Info",
        "action_builder:field": "Why are you unionizing?",
        "action_builder:field_type": "notes",
        "name": "Because we need protections",
        "action_builder:note_response": "protections for healthcare coverage",
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/3c850f2c-8af5-4aae-9627-1faf11a98671"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "osdi:tag": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/68615557-fb83-4c08-b8f6-3e4b7b37f6e7"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:ac15d374-41ec-4f57-9070-140e1e511ed6"
        ],
        "created_date": "2022-02-18T16:55:10.813Z",
        "modified_date": "2022-02-18T16:55:10.813Z",
        "item_type": "entity",
        "action_builder:section": "Basic Info",
        "action_builder:field": "Pronouns",
        "action_builder:field_type": "standard",
        "name": "She/Hers",
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/ac15d374-41ec-4f57-9070-140e1e511ed6"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "osdi:tag": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/689157fd-5e5b-403d-9913-c427a2e6c5bf"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:0f857640-897c-47d7-89ea-736dd5ce1f00"
        ],
        "created_date": "2022-02-18T16:55:02.120Z",
        "modified_date": "2022-02-18T16:55:02.120Z",
        "item_type": "entity",
        "action_builder:section": "Basic Info",
        "action_builder:field": "Number of Kids",
        "action_builder:field_type": "number",
        "name": "1",
        "action_builder:number_response": 1,
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/0f857640-897c-47d7-89ea-736dd5ce1f00"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "osdi:tag": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/63cff13b-e528-4521-9c8b-36d837a1cf05"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:d16dd64c-234e-45de-8317-e82ff72e12e9"
        ],
        "created_date": "2022-02-18T16:54:53.932Z",
        "modified_date": "2022-02-18T16:54:53.932Z",
        "item_type": "entity",
        "action_builder:section": "Basic Info",
        "action_builder:field": "Hiring Date",
        "action_builder:field_type": "date",
        "name": "1/15/2022",
        "action_builder:date_response": "2022-01-15",
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/d16dd64c-234e-45de-8317-e82ff72e12e9"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "osdi:tag": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/588dbacf-0f20-47cf-ad7b-a17f6c39b00f"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:94f3dee9-0ac8-480c-9efd-17dabaef58f8"
        ],
        "created_date": "2022-02-18T16:54:29.477Z",
        "modified_date": "2022-02-18T16:54:29.477Z",
        "item_type": "entity",
        "action_builder:section": "Basic Info",
        "action_builder:field": "Canvassing Shift",
        "action_builder:field_type": "shift",
        "name": "Morning",
        "action_builder:timezone": "America/New_York",
        "action_builder:shift_response": [
          {
            "day": "Monday",
            "start_time": "11:00",
            "end_time": "13:00"
          },
          {
            "day": "Thursday",
            "start_time": "11:00",
            "end_time": "13:00"
          }
        ],
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/94f3dee9-0ac8-480c-9efd-17dabaef58f8"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "osdi:tag": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/b79e1d32-507b-4e7d-8cdd-7d7c9ccb3308"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_builder",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      }
    ],
    "osdi:taggings": [
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/f002be4c-4d9f-4dc8-b858-6c27bf036929"
      },
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/3c850f2c-8af5-4aae-9627-1faf11a98671"
      },
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/ac15d374-41ec-4f57-9070-140e1e511ed6"
      },
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/0f857640-897c-47d7-89ea-736dd5ce1f00"
      },
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/d16dd64c-234e-45de-8317-e82ff72e12e9"
      },
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/94f3dee9-0ac8-480c-9efd-17dabaef58f8"
      }
    ]
  }
}

Scenario: Retrieving an individual tagging resource (GET)

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

Request

					
GET https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/0e51a7e5-321c-4d39-b216-31a57f04e5f4/taggings/37036c91-cfaa-4704-a891-3c2c1ded0bd4

Header:
OSDI-API-Token: your_api_key_here

Response

			 	 
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate					 
					 
{
  "origin_system": "Action Builder",
  "identifiers": [
    "action_builder:94f3dee9-0ac8-480c-9efd-17dabaef58f8"
  ],
  "created_date": "2022-02-18T16:54:29.477Z",
  "modified_date": "2022-02-18T16:54:29.477Z",
  "item_type": "entity",
  "action_builder:section": "Basic Info",
  "action_builder:field": "Canvassing Shift",
  "action_builder:field_type": "shift",
  "name": "Morning",
  "action_builder:timezone": "America/New_York",
  "action_builder:shift_response": [
    {
      "day": "Monday",
      "start_time": "11:00",
      "end_time": "13:00"
    },
    {
      "day": "Thursday",
      "start_time": "11:00",
      "end_time": "13:00"
    }
  ],
  "_links": {
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_builder",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings/94f3dee9-0ac8-480c-9efd-17dabaef58f8"
    },
    "action_builder:campaign": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
    },
    "osdi:tag": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/b79e1d32-507b-4e7d-8cdd-7d7c9ccb3308"
    },
    "osdi:person": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
    }
  }
}

Scenario: POST/PUT

Posting and putting a tagging is not allowed via the API. Requests will return an error.

Scenario: Deleting an individual tagging resource (DELETE)

Deleting a tagging resource will remove it from the attached person or connection.

Request

					
DELETE https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/tags/63cff13b-e528-4521-9c8b-36d837a1cf05/taggings/0f857640-897c-47d7-89ea-736dd5ce1f00
Header:
OSDI-API-Token: your_api_key_here

Response

			 	 
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate					 
					 
{
  "message": "Tag has been removed from entity"
}