Alerts have two origins. Typically, alerts are generated whenever a Unit21 detection tool (like a rule) flags an object, like an entity. However, your organization can also send alerts generated from your in-house detection systems.

The /alerts endpoint can create, list, and update alerts.

ENDPOINT

DESCRIPTION

POST /alerts/create

Creates an alert.

PUT /alerts/<unit21_id>/update

Updates an existing alert.

PUT /alerts/<unit21_id>/link-media

Adds an image/media to an alert.

GET /alerts/<unit21_id>

Retrieves the details of an existing alert.

POST /alerts/list

Retrieves a list of all alerts.

List Alert

When listing alerts, you can use the following filter parameters:

Note that all list inputs function as an "or" filter, as in any one of the values must match the selected alert(s)

Field

Type

Description

types

String[]

Must be list of alert types: tm, kyc

created_after

Numeric

Alerts created on or after this unix timestamp

created_before

Numeric

Alerts created before this unix timestamp

dispositions

String[]

List of alert disposition states (defined on an integration basis)

dispositioned_after

Numeric

Alerts with a disposition most recently updated after this unix timestamp

dispositioned_before

Numeric

Alerts with a disposition most recently updated before this unix timestamp

dispositioned_by

String[]

List of agent emails. Returns alerts with a disposition most recently changed by agents in the list

rules

Numeric[]

List of Unit21 rule ids that are associated with the alert

associated_entities

Numeric[]

List of Unit21 entity ids associated with this alert

associated_events

Numeric[]

List of Unit21 event ids associated with this alert

associated_instruments

Numeric[]

List of Unit21 instrument ids associated with this alert

sources

String[]

Must be list of alert sources: INTERNAL, EXTERNAL

statuses

String[]

Must be list of alert statuses: OPEN, CLOSED

tag_filters

String[]

List of string tags in the format key:value or key to associate this alert with (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 10

offset

Numeric

The offset for pagination. Default is 1

options

Object

Options for the data included in the returned alerts. Removing unneeded options can improve response speed

curl -X POST \
  https://<API_ENDPOINT>/v1/alerts/list \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
        "created_after": 1591992745,
        "created_before": 1591993745,
        "types": ["tm", "kyc"],
        "sources": ["INTERNAL", "EXTERNAL"],
        "statuses": ["OPEN", "CLOSED"],
        "dispositions": ["false_positive", "true_positive"],
        "rules": [1234],
        "associated_entities": [123, 345],
        "associated_instruments": [523, 335],
        "associated_events": [3423, 33445],
        "tag_filters": ["samplekey", "scenario_type:blacklist"],
        "dispositioned_before": 1591992745,
        "dispositioned_after": 1591992745,
        "dispositioned_by": "[email protected]"
        "limit": 10,
        "offset": 1
        "options": {
          "include_associations": false,
          "include_actions": false,
          "include_checklist": false
        }
  }'
HTTP/1.1 200 OK
Content-Type: application/json
{
  "alerts": [
    {
        "alert_id": "12345",
        "alert_type": "tm",
        "assigned_to": "[email protected]",
        "created_at": 1597739123,
        "custom_data": {},
        "description": "Alert description",
        "disposition": "REJECTED",
        "dispositioned_at": 1597849123,
        "dispositioned_by": "[email protected]",
        "entities": [
            {
              "entity_id": "userA-ef3d5d41-9ac4-4071-b1fe-7dd77c80a4e8",
              "entity_type": "user",
              "resolution": "UNRESOLVED",
              "unit21_id": 3789
            }
        ],
        "events": [
            {
              "event_id": "txnBulk-11-ef3d5d41-6bc4-4070-b6ed-4dd77c90a5e8",
              "event_type": "transaction",
              "resolution": "UNRESOLVED",
              "unit21_id": 98
            }
        ],
        "instruments": [
            {
                "instrument_id": "instrument-3012850a",
                "instrument_type": "wallet",
                "unit21_id": 427,
                "resolution": "UNRESOLVED"
            }
        ]
        "rules": [
            {
                "rule_id": "123",
                "unit21_id": 456
            }
        ],
        "source": "INTERNAL",
        "status": "CLOSED",
        "tags": [
            "scenario_type:blacklist", "sameplekey:samplevalue"
        ],
        "title": "Alert Title",
        "unit21_id": 101,
        "actions": [
          {
            "subdispositions": [{"subdisposition": "TITLE", "value": "MISSING_DOCUMENTS"}],
            "disposition": "REJECTED",
            "status_changed_to": "CLOSED",
            "action_time": 1597849123,
            "author": "[email protected]",
            "disposition_notes": "free form agent text describing the action/resaons"
          }
        ]
    }
  ],
  "response_count": 1,
  "total_count": 10
}

Create and Update Alert

curl -X POST \
  https://<API_ENDPOINT>/v1/alerts/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
      "alert_id": "alertD-{{randId}}",
      "alert_type": "tm",
      "verification_result_id": 41,
      "created_at": 1580763704,
      "title": "Alert for fraud ring fool",
      "description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
      "status": "OPEN",
      "tags": [
          "source:intuit_internal"
        ],
      "rules": [
        "COLLUSION_3RD_PARTY",
        "LAYERING_SCENARIO_A"
      ],
      "events": [
        {
          "event_id": "txnA-{{randId}}",
          "event_type": "transaction"
        }
      ],
      "entities": [
        {
          "entity_id": "userA-{{randId}}",
          "entity_type": "user"
        },
        {
          "entity_id": "businessA-{{randId}}",
          "entity_type": "business"
        }
      ],
      "custom_data": {
        "priority": "5"
      },
      "options": {
      "merge_custom_data": true,
      "list_merge_strategy": "union"
      }
    }'

Please note that if verification_result_id is included, it will link the entity that is associated with the verification result with the alert regardless of the list_merge_strategy provided in the options field.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "alert_id": "alertD-38f8e0Rwdf63nld71112345132UeUKFWE123",
    "previously_existed": false,
    "unit21_id": "9219815"
}

If the alert already exists, it will not be updated or upserted, instead you will get a 409 error code:

HTTP/1.1 409 CONFLICT
Content-Type: application/json
{
    "error_code": "duplicate resource",
    "message": "Alert with id alertD-38f8e0Rwdf63nld71112345132UeUKFWE123 already exists",
    "unit21_id": "9219815"
}

You must use the /alert/update endpoint to update an alert.

curl -X PUT \
  https://<API_ENDPOINT>/v1/alerts/<unit21_id>/update \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "status": "CLOSED",
    "tags": [
      "type:historical_deviation",
      "tier:one",
      "account_type:premium"
    ],
    "custom_data": {
      "estimated_volume": 901032.13,
      "tier": 4,
      "quality_check": false,
      "case_details": {
        "date_start": "02-23-2019",
        "filing_id": "f2771140"
      }
    },
    "options": {
      "merge_custom_data": true,
      "list_merge_strategy": "union"
    }
  }'
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "8483",
  "alert_id": "alertA-028eb01a-f8d3-42fb-b398-785b596ee4cb"
}

Add Objects to Alerts

You can add the following objects to an alert:

Field

Type

Description

rules

String[]

Unique identifier of the rules/triggers/scenarios that triggered this alert.

events

Object[]

Transactions affiliated with the alert. Each object must consist of a event_id and event_type field

entities

Object[]

Users or businesses affiliated with the alert. Each object must consist of an entity_id and entity_type field

instruments

String[]

Unique identifiers of any instruments affiliated with the alert

Batch Alert Requests

The /alerts/create API accepts batch uploads:

  • each batch must contains no more than 250 alerts,
  • and the total size of the POST body must be smaller than 100mb.
curl -X POST \
  https://<API_ENDPOINT>/v1/alerts/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "alerts": [
        {
            "alert_id": "alertB-{{randId}}",
            "created_at": 1580763704,
            "title": "Alert for fraud ring fool",
            "description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
            "status": "OPEN",
            "tags": [
                "source:intuit_internal"
                ],
            "rules": [
                "COLLUSION_3RD_PARTY",
                "LAYERING_SCENARIO_A"
            ],
            "events": [
                {
                "event_id": "txnA-{{randId}}",
                "event_type": "transaction"
                }
            ],
            "entities": [
                {
                    "entity_id": "userA-{{randId}}",
                    "entity_type": "user"
                },
                {
                    "entity_id": "businessA-{{randId}}",
                    "entity_type": "business"
                }
            ],
            "custom_data": {
                "priority": "5"
            }
        },
                {
            "alert_id": "alertC-{{randId}}",
            "created_at": 1580763704,
            "title": "Alert for fraud ring fool",
            "description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
            "status": "OPEN",
            "tags": [
                "source:intuit_internal"
                ],
            "rules": [
                "COLLUSION_3RD_PARTY",
                "LAYERING_SCENARIO_A"
            ],
            "events": [
                {
                "event_id": "txnA-{{randId}}",
                "event_type": "transaction"
                }
            ],
            "entities": [
                {
                    "entity_id": "userA-{{randId}}",
                    "entity_type": "user"
                },
                {
                    "entity_id": "businessA-{{randId}}",
                    "entity_type": "business"
                }
            ],
            "custom_data": {
                "priority": "5"
            }
        }
    ]
}'

When uploading a batch of alerts, any entity-level options will be ignored; only the top-level options provided will be used.

If there are any data validation errors in the data that is passed (such as missing required fields) the entire batch request will fail with a 400 response code.

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
    "error_code": "invalid_input",
    "message": "Missing required field `alert_id`"
}

The response contains a count of all the alerts processed in the batch along with a list of objects containing three fields. The list allows you to map the alert_id passed to our API with our internal unit21_id. The response also indicates whether this alert previously existed or not.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "alerts": [
        {
            "alert_id": "alertB-38f8e0Rwdf63nld71112345132UeUKFWE123",
            "previously_existed": true,
            "unit21_id": "9141601"
        },
        {
            "alert_id": "alertC-38f8e0Rwdf63nld71112345132UeUKFWE123",
            "previously_existed": false,
            "unit21_id": "9219814"
        }
    ],
    "count": 2
}

For alerts that previously already existed in our system, previously_existed will be true.

Delete Alerts

Deleting alerts is not allowed.

Options for the Endpoint

curl -X POST \
  https://<API_ENDPOINT>/v1/alerts/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "options": {
      "merge_custom_data": true,
      "list_merge_strategy": "union"
    }
  }'

The following fields are options for the endpoint:

Field

Type

Description

include_associations

Boolean

If true, the response will include all entities, events & instruments associated with the alert.

include_actions

Boolean

If true, the response will include actions in the response which is a list of all actions taken on the alert including disposition changes, status changes, reassignments and the authors email.

include_checklist

Boolean

If true, the response will include checklists in the response which is a list of all checklist items an agent must complete for the alert investigation.