Tags are a flexible and dynamic solution for object-labeling in Unit21's system. They can be associated to alerts, cases, rules, SARs, entities, events, instruments, agents, and action triggers.

Tags can either be applied manually by agents on the Unit21 dashboard or programmatically via API. The tag associations API is a simple interface to extract tags-object associations from Unit21's system for your own processing.

You can use the /tag-associations endpoint to explore these associations.

ENDPOINT

DESCRIPTION

POST /tag-associations/list

Retrieves a list of of tags/object pairs that matches the filter criteria passed in.

List Tag Associations

This API returns an object containing of all the tag-associations matching your filter criteria, and sorts/paginates results chronologically by when the tag-to-object association was created.

curl -X POST \
  https://<API_ENDPOINT>/v1/tag-associations/list \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "created_after": 1597198562,
    "created_before": 1598481792,
    "object_types": [
        "entity",
        "event",
        "instrument",
        "alert",
        "case",
        "sar",
        "agent",
        "rule"
    ],
    "tag_filters": [
        "type:aml",
        "account_type"
    ],
    "limit": 1000,
    "offset": 1
}'
HTTP/1.1 200 OK
Content-Type: application/json
{
  "tag_associations": [
    {
      "created_at": 1598405517,
      "object_id": "351906",
      "object_type": "alert",
      "tag": "account_type:market2"
    },
    {
      "created_at": 1598398976,
      "object_id": "351786",
      "object_type": "alert",
      "tag": "account_type:market2"
    },
    ...
    {
      "created_at": 1598382408,
      "object_id": "346310",
      "object_type": "entity",
      "tag": "type:aml"
    }
  ],
  "response_count": 1000,
  "total_count": 29361
}

To list tag association, we support filters to narrow down the results:

Field

Type

Description

created_after

Numeric

Tag associations created on or after this unix timestamp.

created_before

Numeric

Tag associations created before this unix timestamp.

object_types

String[]

List of object types to match against. Supported values are alert, case, sar, rule, agent, event, entity, and instrument. Specifying [entity, alert] means that we will only match against tags associated with entities and alerts in the system, and will not return results of tags associated with rules, events etc. If more than one value is provided to object_types and object_id is specified, an error will be thrown.

object_id

String

String representing the unit21 ID of the object you want to get tag associations for. If this is specified and object_types contains more than one value, an error will be thrown.

tag_filters

String[]

List of string tags in the format key:value or key to match against (e.g. alert_type:high_velocity or alert_type). If only the key is provided, we will match against all tags with that key.

limit

Numeric

A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 1000.

offset

Numeric

The offset for pagination. Default is 1.