Cases are usually active investigations, which may span multiple events, entities and documents. They can be directly escalated into a suspicious activity report.

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

ENDPOINT

DESCRIPTION

POST /cases/create

Creates a case.

PUT /cases/<unit21_id>/update

Updates an existing case.

PUT /cases/<unit21_id>/link-media

Adds an image/media to a case.

GET /cases/<unit21_id>

Gets an existing case.

POST /cases/list

Retrieves a list of all cases.

List Case

When listing cases, 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

created_after

Numeric

Cases created on or after this unix timestamp

created_before

Numeric

Cases created before this unix timestamp

dispositions

String[]

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

dispositioned_after

Numeric

Cases with a disposition most recently updated after this unix timestamp

dispositioned_before

Numeric

Cases with a disposition most recently updated before this unix timestamp

dispositioned_by

String[]

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

rules

Numeric[]

List of Unit21 rule ids that are associated with the case

associated_entities

Numeric[]

List of Unit21 entity ids associated with this case.

associated_events

Numeric[]

List of Unit21 event ids associated with this case.

associated_alerts

Numeric[]

List of Unit21 alert ids associated with this case.

sources

String[]

Must be list of case sources: "INTERNAL", "EXTERNAL"

statuses

String[]

Must be list of case statuses: "OPEN", "CLOSED"

tag_filters

String[]

List of string tags in the format key:value or key to associate this case with (e.g. case_type:high_velocity or case_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 cases. Removing unneeded options can improve response speed

curl -X POST \
  https://<API_ENDPOINT>/v1/cases/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"],
        "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
{
  "cases": [        
    {
      "actions": [],
      "alerts": [],
      "assigned_to": null,
      "case_id": null,
      "checklist": {},
      "created_at": 1576220360,
      "created_by": "[email protected]",
      "custom_data": {},
      "descendant_sar_filing": [],
      "description": "zxcv",
      "disposition": "UNRESOLVED",
      "dispositioned_at": null,
      "dispositioned_by": null,
      "entities": [],
      "events": [],
      "rules": [],
      "source": "INTERNAL",
      "status": "CLOSED",
      "tags": [],
      "title": "asdf",
      "unit21_id": "2"
    },
    ...
  ],
  "response_count": 10,
  "total_count": 100
}

Create and Update Case

curl -X POST \
  https://<API_ENDPOINT>/v1/cases/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
  "case_id": "caseA-123",
  "start_date": 1588963704,
  "end_date": 1589963704,
  "title": "Active fraud investigation against x group",
  "description": "suspected money laundering circle",
  "status": "OPEN",
  "tags": [
      "source:intuit_internal"
    ],
  "events": [
    {
      "event_id": "txnA-123",
      "event_type": "transaction"
    }
  ],
  "entities": [
    {
      "entity_id": "userA-123",
      "entity_type": "user"
    },
    {
      "entity_id": "businessA-123",
      "entity_type": "business"
    }
  ],
  "custom_data": {
    "priority": "5"
  }
}'
HTTP/1.1 200 OK
Content-Type: application/json
{
  "unit21_id": "8483",
  "case_id": "caseA-123"
}

If the case 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": "Case with id caseA-38f8e0Rwdf63nld71112345132UeUKFWE123 already exists",
    "unit21_id": "9124881"
}

You must use the /case/update endpoint to update a case.

curl -X PUT \
  https://<API_ENDPOINT>/v1/cases/<unit21_id>/update \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
  "title": "Active fraud investigation against x group",
  "description": "suspected money laundering circle",
  "status": "CLOSED",
  "tags": [
      "source:intuit_internal"
    ],
  "custom_data": {
    "priority": "5"
  }
}'
HTTP/1.1 200 OK
Content-Type: application/json
{
  "unit21_id": "8483",
  "case_id": "caseA-123"
}

Add Objects to Cases

You can add the following objects to an case:

Field

Type

Description

rules

String[]

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

events

Object[]

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

entities

Object[]

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

instruments

String[]

Unique identifiers of any instruments affiliated with the case

curl -X PUT \
  https://<API_ENDPOINT>/v1/cases/<unit21_id>/add-objects \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "entities": [
      {
        "entity_id": "jio23non",
        "entity_type": "user"
      }
    ]
  }'
HTTP/1.1 200 OK
Content-Type: application/json
{
  "unit21_id": "8483",
  "case_id": "caseA-123"
}

Batch Case Requests

The /case/create API accepts batch uploads:

  • each batch must contains no more than 250 cases,
  • and the total size of the POST body must be smaller than 100mb.
curl -X POST \
  https://<API_ENDPOINT>/v1/cases/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "cases": [
        {
            "case_id": "caseA}",
            "start_date": 1588963704,
            "end_date": 1589963704,
            "title": "Imported case from internal flagging engine",
            "description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
            "status": "OPEN",
            "tags": [
                "source:intuit_internal"
                ],
            "events": [
                {
                "event_id": "txnA",
                "event_type": "transaction"
                }
            ],
            "entities": [
                {
                    "entity_id": "userA",
                    "entity_type": "user"
                },
                {
                    "entity_id": "businessA",
                    "entity_type": "business"
                }
            ],
            "custom_data": {
                "priority": "510"
            }
        },
        {
            "case_id": "caseB",
            "start_date": 1588963704,
            "end_date": 1589963704,
            "title": "Imported case from internal flagging engine",
            "description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
            "status": "OPEN",
            "tags": [
                "source:intuit_internal"
                ],
            "events": [
                {
                "event_id": "txnB",
                "event_type": "transaction"
                }
            ],
            "entities": [
                {
                    "entity_id": "userB",
                    "entity_type": "user"
                },
                {
                    "entity_id": "businessB",
                    "entity_type": "business"
                }
            ],
            "custom_data": {
                "priority": "510"
            }
        }
    ]
}'

When uploading a batch of cases, any case-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 `case_id`"
}

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

HTTP/1.1 200 OK
Content-Type: application/json
{
    "cases": [
        {
            "case_id": "caseA",
            "previously_existed": true,
            "unit21_id": "7729780"
        },
        {
            "case_id": "caseB",
            "previously_existed": false,
            "unit21_id": "9220307"
        }
    ],
    "count": 2
}

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

Delete Cases

Deleting cases is not allowed.

Options for the Endpoint

curl -X POST \
  https://<API_ENDPOINT>/v1/cases/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "options": {
        "include_actions": true,
        "include_associations": true,
        "include_checklist": true
    }
  }'

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 case.

include_actions

Boolean

If true, the response will include actions in the response which is a list of all actions taken on the case 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 case investigation.