Time	Status	User Agent
Retrieving recent requests…

Overview

Use this method to search for cases in Case Management using complex, multi-level filter criteria. The endpoint supports both direct lookup by case ID and structured field-based filtering with logical grouping.

The response returns full case data, matching the detail level available in the Case Management UI. This ensures that all required information is available in a single request without the need for additional follow-up calls.

The ids and criteria parameters can be used together in the same request. When both are present, results matching either condition are included in the response.

📘
Notes

The request body must be a non-empty object. Sending an empty body, omitting both ids and criteria, or referencing field names that are not part of the available filters list results in an HTTP 400 Bad Request error.

This endpoint is available only in the paid version of Case Management 2.0 and does not apply to earlier versions.

You can retrieve available case filters via this endpoint.

Criteria logic

Construct the request based on the required purpose. The criteria array accepts two types of objects:

`SerializedComplexCriteria`

Used for grouping conditions. Includes the following fields:

Field	Type	Description
`op`	String	Logical operator. Accepted values: `$and`, `$or`.
`children`	Array of objects	Nested list of criteria objects, which can themselves be `SerializedComplexCriteria` and/or `SerializedFieldCriteria`.

Logical operators

The following operators are supported in SerializedComplexCriteria:

Operator	Description
`$and`	Returns results that match all of the specified conditions.
`$or`	Returns results that match at least one of the specified conditions.

Example:

{
  "op": "$and",
  "children": [
    {
      "field": "caseReview.status",
      "op": "=",
      "values": [
        "pending"
      ]
    },
    {
      "op": "$or",
      "children": [
        {
          "field": "createdAt",
          "op": ">=",
          "values": [
            "2025-12-09 00:00:00"
          ]
        },
        {
          "field": "updatedAt",
          "op": ">=",
          "values": [
            "2025-12-09 00:00:00"
          ]
        }
      ]
    },
    {
      "field": "createdByType",
      "op": "=",
      "values": [
        "user"
      ]
    }
  ]
}

`SerializedFieldCriteria`

Used for field-level matching. Includes the following fields:

Field	Type	Description
`field`	String	Name of the case field to filter on. Must be one of the available case filters .
`op`	String	Comparison operator. Accepted values: `=`, `<>`, `>`, `>=`, `<`, `<=`, `$all`, `$contains`.
`values`	Array of strings	List of values to compare the field against.

Comparison operators

The following operators are supported in SerializedFieldCriteria:

Operator	Description
`=`	Exact match. The field value must equal the specified value.
`<>`	Not equal. The field value must differ from the specified value.
`>`	Greater than. Applicable to numeric and date fields.
`>=`	Greater than or equal to. Applicable to numeric and date fields.
`<`	Less than. Applicable to numeric and date fields.
`<=`	Less than or equal to. Applicable to numeric and date fields.
`$all`	All values match. The field must contain all values specified in the `values` array.
`$contains`	Contains match. The field value must match at least one value from the `values` array.

Example:

{
  "field": "caseReview.status",
  "op": "=",
  "values": [
    "pending",
    "open"
  ]
}

Request examples

// Average exanple with dummy data.

curl -X POST \
     'https://api.sumsub.com/resources/api/caseManagement/v2/cases/byFilter?limit=100&countTotalItems=false' \
     -H 'content-type: application/json'
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>' \
     -d '{
           "ids": [
             "caseId1",
             "caseId2"
           ],
           "criteria": [
             {
               "op": "$and",
               "children": [
                 {
                   "field": "caseReview.status",
                   "op": "=",
                   "values": [
                     "pending"
                   ]
                 },
                 {
                   "op": "$or",
                   "children": [
                     {
                       "field": "createdAt",
                       "op": ">=",
                       "values": [
                         "2025-12-09 00:00:00+0000"
                       ]
                     },
                     {
                       "field": "updatedAt",
                       "op": ">=",
                       "values": [
                         "2025-12-09 00:00:00+0000"
                       ]
                     }
                   ]
                 },
                 {
                   "field": "createdByType",
                   "op": "=",
                   "values": [
                     "user"
                   ]
                 }
               ]
             }
           ]
         }'

// The following example retrieves cases that were created after January 1, 2024 and have a status of either `open` or `pending`, sorted from newest to oldest, with a total item count included.

curl -X POST \
  'https://api.sumsub.com/resources/api/caseManagement/v2/cases/byFilter?offset=0&limit=50&order=-createdAt&countTotalItems=true' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Token: <your-app-token>' \
  -H 'X-App-Access-Sig: <your-signature>' \
  -H 'X-App-Access-Ts: <unix-timestamp>' \
  -d '{
    "criteria": [
      {
        "op": "$and",
        "children": [
          {
            "field": "createdAt",
            "op": ">",
            "values": ["2024-01-01 00:00:00+0000"]
          },
          {
            "field": "status",
            "op": "$contains",
            "values": ["open", "pending"]
          }
        ]
      }
    ]
  }'

// The following example retrieves a specific set of cases by their IDs.

curl -X POST \
  'https://api.sumsub.com/resources/api/caseManagement/v2/cases/byFilter' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Token: <your-app-token>' \
  -H 'X-App-Access-Sig: <your-signature>' \
  -H 'X-App-Access-Ts: <unix-timestamp>' \
  -d '{
    "ids": [
        "case_001abc",
        "case_002def",
        "case_003ghi"
    ]
  }'

// The following example retrieves open cases associated with the applicant with `applicant_id`, within the blueprint `blueprint_id`, created after March 17.

curl -X POST \
  'https://api.sumsub.com/resources/api/caseManagement/v2/cases/byFilter' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Token: <your-app-token>' \
  -H 'X-App-Access-Sig: <your-signature>' \
  -H 'X-App-Access-Ts: <unix-timestamp>' \
  -d '{
        "ids": [],
        "criteria": [
          {
            "field": "caseReview.status",
            "op": "=",
            "values": ["open"]
          }, {
            "field": "applicantReference.applicantId",
            "op": "=",
            "values": ["applicant_id"]
          },
          {
            "field": "blueprintReference.blueprintId",
            "op": "=",
            "values": ["blueprint_id"]
          }, {
            "field": "createdAt",
            "op": ">=",
            "values": ["2026-03-17 00:00:00+0000"]  
          }
        ]
      }'

Response explained

A successful response returns a paginated list of full case objects wrapped in a list object.

Top-level fields

Field	Type	Description
`list`	Object	Wrapper object containing results and pagination metadata.
`list.items`	Array of objects	List of case objects matching the filter criteria.
`list.totalItems`	Integer	Total number of matching cases. Only present when `countTotalItems=true` is set in the query.
`list.pageInfo`	Object	Pagination details for the current response.

`pageInfo` attributes

The table describes the pageInfo attributes.

Field	Type	Description
`limit`	Integer	Maximum number of items returned in this response.
`offset`	Integer	Offset used for this page of results.

`items` element fields

Each item object represents an individual case entity matching the filter criteria specified in the request.

Field	Type	Description
`id`	String	Unique case identifier.
`name`	String	Case name.
`applicantReference`	Object	Reference data for the applicant associated with the case.
`createdByType`	String	Indicates the type of entity that created the case. Possible values: `byOfficer`, `byRule`, `byWorkflow`, `byOngoingAmlHit`, `byApi`.
`groupByType`	String	Grouping type used for the case.
`createdByRule`	Object	Information about the rule that created the case. Returned only if `"createdByType": "byRule"`.
`createdByOfficer`	String	Officer's identifier. Returned only if `"createdByType": "byOfficer"`.
`createdByWorkflowRef`	Object	Information about the workflow that created the case. Returned only if `"createdByType": "byWorkflow"`.
`createdAt`	Date	Date and time when the case was created, in the format `yyyy-MM-dd HH:mm:ssZZ`.
`updatedAt`	Date	Date and time when the case was last updated, in the format `yyyy-MM-dd HH:mm:ssZZ`.
`totalAmountInDefaultCurrency`	Double	Total amount of all transactions submitted for the case, in the default currency. Returned if at least one transaction was submitted in the request.
`clientId`	String	Unique identifier of you as our client in the Sumsub system. This identifier is assigned to you when you are registered in and get access to the Sumsub system. It usually resembles your name or your company name. `clientId` is automatically added to the applicant profile when it is created.
`review`	Object	Includes case review data. Note: This field is deprecated and will be removed once KM1 support ends.
`applicantInfo`	Object	General information about the applicant associated with the case.
`blueprintReference`	Object	Includes reference data of the blueprint assigned to the case.
`caseReview`	Object	The current review state and checklist of the case.
`amlCases`	Array of objects	A list of AML cases associated with the case.
`priority`	String	Case priority (`low`, `medium`, `high`). Defaults to `medium`.

`applicantReference` attributes

This table describes the applicantReference attributes.

Field	Type	Description
`applicantId`	String	Unique identifier of the applicant in the Sumsub system.
`fullName`	String	Applicant's full name.

`createdByRule` attributes

Returned only if "createdByType": "byRule".

Field	Type	Description
`id`	String	Unique identifier of the rule.
`name`	String	Name of the rule.
`title`	String	Display name of the rule.
`revision`	Integer	Revision number.

`createdByWorkflowRef` attributes

Returned only if "createdByType": "byWorkflow".

Field	Type	Description
`id`	String	Unique identifier of the workflow.
`title`	String	Name of the action from the workflow.

`review` attributes

This table describes the review attributes.

Field	Type	Description
`reviewId`	String	Unique review identifier.
`attemptId`	String	Unique identifier of the current case verification attempt.
`attemptCnt`	Integer	Sequential number of the current case verification attempt.
`createDate`	Date	Date and time when the case review was initiated in the Sumsub system, in the format `yyyy-MM-dd HH:mm:ssZZ`.
`reviewStatus`	String	Case review status (for example, `init`).

`applicantInfo` attributes

This table describes the applicantInfo attributes.

Field	Type	Description
`firstName`	String	Applicant's first name in the original language.
`firstNameEn`	String	Automatic's transliteration of the applicant first name into Latin characters.
`middleName`	String	Applicant's middle name in the original language.
`middleNameEn`	String	Automatic's transliteration of the applicant middle name into Latin characters.
`lastName`	String	Applicant's last name in the original language.
`lastNameEn`	String	Automatic's transliteration of the applicant last name into Latin characters.
`dob`	String	Applicant's date of birth as a Unix timestamp in milliseconds.
`country`	String	Applicant's country as an ISO 3166-1 alpha-3 country code (for example, `DEU`, `GBR`, `ARG`)..

`blueprintReference` attributes

This table describes the blueprintReference attributes.

Field	Type	Description
`name`	String	Name of the assigned blueprint.
`blueprintId`	String	Unique identifier of the blueprint.

`caseReview` attributes

The table describes the caseReview attributes.

Field Type Description

Field	Type	Description
`status`	String	Current status of the case review. Possible values: `open`, `awaitingUser`, `blocked`, `resolvedFalsePositive`, `resolvedPotentialThreat`.
`checklistState`	Object	Checklist state associated with the case.

status

String

Current status of the case review.

Possible values: open, awaitingUser, blocked, resolvedFalsePositive, resolvedPotentialThreat.

checklistState Object Checklist state associated with the case.

`checklistState.checklist[]`

Field	Type	Description
`name`	String	The name of the checklist item.
`checked`	Boolean	Indicates whether the checklist item is completed (`true`) or not (`false`).

`amlCases[]`

Field	Type	Description
`amlCaseId`	String	Unique identifier of the AML case.

Response examples

If the request is successfully sent and processed, you will get a response like the one below.

{
  "list": {
    "items": [
      {
        "id": "69ce2a555b353c0000000000",
        "name": "Check counterparty for AML (sanctions, peps, etc.) - John Doe",
        "applicantReference": {
          "applicantId": "69a6974e0ad36b0000000000",
          "fullName": "John Doe"
        },
        "createdByType": "byRule",
        "groupByType": "byRule",
        "createdByRule": {
          "id": "6970bfd90eefbc0000000000",
          "name": "che-cou-for-aml-san-peps-etc-DKsb",
          "title": "Check counterparty for AML (sanctions, peps, etc.)",
          "revision": 3
        },
        "createdAt": "2026-04-02 08:35:33+0000",
        "updatedAt": "2026-04-02 08:35:33+0000",
        "totalAmountInDefaultCurrency": 50000,
        "clientId": "your_cool_id",
        "review": {
          "reviewId": "KlLJY",
          "attemptId": "sGjxs",
          "attemptCnt": 0,
          "createDate": "2026-04-02 08:35:33+0000",
          "reviewStatus": "init"
        },
        "applicantInfo": {
          "firstName": "John",
          "firstNameEn": "John",
          "middleName": "Jack",
          "middleNameEn": "Jack",
          "lastName": "Doe",
          "lastNameEn": "Doe",
          "country": "USA"
        },
        "blueprintReference": {
          "name": "brand new BP",
          "blueprintId": "6970bf0a0eefbc0000000000"
        },
        "caseReview": {
          "status": "open",
          "checklistState": {
            "checklist": [
              {
                "name": "checklist action 1",
                "checked": false
              },
              {
                "name": "checklist action 2",
                "checked": false
              },
              {
                "name": "checklist action 3",
                "checked": false
              },
              {
                "name": "checklist action 4",
                "checked": false
              }
            ]
          }
        },
        "amlCases": [
          {
            "amlCaseId": "69ce2a535b353c0000000000"
          }
        ],
        "priority": "medium"
      },
      {
        "id": "69ce2a555b353c0000000000",
        "name": "Check counterparty for AML (sanctions, peps, etc.) - John Doe",
        "applicantReference": {
          "applicantId": "69a6974e0ad36b0000000000",
          "fullName": "John Doe"
        },
        "createdByType": "byRule",
        "groupByType": "byRule",
        "createdByRule": {
          "id": "6970bfd90eefbc0000000000",
          "name": "che-cou-for-aml-san-peps-etc-DKsb",
          "title": "Check counterparty for AML (sanctions, peps, etc.)",
          "revision": 3
        },
        "createdAt": "2026-04-02 08:35:33+0000",
        "updatedAt": "2026-04-02 08:35:33+0000",
        "totalAmountInDefaultCurrency": 50000,
        "clientId": "your_cool_id",
        "review": {
          "reviewId": "KlLJY",
          "attemptId": "sGjxs",
          "attemptCnt": 0,
          "createDate": "2026-04-02 08:35:33+0000",
          "reviewStatus": "init"
        },
        "applicantInfo": {
          "firstName": "John",
          "firstNameEn": "John",
          "middleName": "Jack",
          "middleNameEn": "Jack",
          "lastName": "Doe",
          "lastNameEn": "Doe",
          "country": "USA"
        },
        "blueprintReference": {
          "name": "brand new BP",
          "blueprintId": "6970bf0a0eefbc0000000000"
        },
        "caseReview": {
          "status": "open",
          "checklistState": {
            "checklist": [
              {
                "name": "checklist action 1",
                "checked": false
              },
              {
                "name": "checklist action 2",
                "checked": false
              },
              {
                "name": "checklist action 3",
                "checked": false
              },
              {
                "name": "checklist action 4",
                "checked": false
              }
            ]
          }
        },
        "amlCases": [
          {
            "amlCaseId": "69ce2a535b353c0000000000"
          }
        ],
        "priority": "medium"
      }
    ],
    "totalItems": 2,
    "pageInfo": {
      "limit": 10,
      "offset": 0
    }
  }
}

If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:

// In this example, the method returns HTTP 400 (Bad Request) because the filtering parameters are malformed, the request body is empty, or invalid field names are provided.

{
    "code": 400,
    "correlationId": "b66c98b82f7ed5e026fb4965975f6739",
    "description": "Invalid parameters provided",
    "type": "de.smtdp.commons.service.exceptions.ServiceException"
}

Overview

Notes

Criteria logic

SerializedComplexCriteria

Logical operators

SerializedFieldCriteria

Comparison operators

Request examples

Response explained

Top-level fields

pageInfo attributes

items element fields

applicantReference attributes

createdByRule attributes

createdByWorkflowRef attributes

review attributes

applicantInfo attributes

blueprintReference attributes

caseReview attributes

checklistState.checklist[]

amlCases[]

Response examples

`SerializedComplexCriteria`

`SerializedFieldCriteria`

`pageInfo` attributes

`items` element fields

`applicantReference` attributes

`createdByRule` attributes

`createdByWorkflowRef` attributes

`review` attributes

`applicantInfo` attributes

`blueprintReference` attributes

`caseReview` attributes

`checklistState.checklist[]`

`amlCases[]`