Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

Overview

Use this method to override an applicant's Transaction Monitoring risk level from your own system rather than through the Dashboard. Send the target risk level name, a comment explaining the change, and, optionally, a date until which the level stays locked (frozen from automatic recalculation). The comment is required for every override except unlocking a risk level (see Notes below).

The method returns the applicant profile with the updated assessment.

Required permissions

To use this method, your app token must have the following permissions:

Change applicant risk level
View check results (required to receive the assessment object in the response)

Transaction Monitoring must be enabled for your account. Otherwise, the method returns 403 Forbidden.

Use case

Use this method to synchronize a risk level computed or reviewed in your own fraud or compliance system with the applicant profile in Sumsub, without needing a human to act in the Dashboard.

You can also use it to unlock a risk level: send the applicant's current risk level label without freezeUntil. The risk level stays the same, but it is no longer frozen and becomes subject to automatic recalculation again. See the Unlock request example below.

📘
Notes

label must exactly match one of the risk level names already configured in the Dashboard risk level settings. The match is case-sensitive (for example, High risk and High Risk are different names). An unrecognized name is rejected with a 400 error.

comment is required for any override except unlocking. If you change the risk level or set freezeUntil, a request without comment is rejected with a 400 error. The comment is optional only when you unlock a risk level, that is, when label is the same as the applicant's current risk level and freezeUntil is omitted.

If you omit freezeUntil, the risk level is assigned but not locked. It remains subject to automatic recalculation.

freezeUntil accepts ISO 8601 input (for example, 2026-12-31T23:59:59+0000) but is echoed back in the response in a different format (yyyy-MM-dd HH:mm:ss±HHMM, for example, 2027-05-29 11:59:02+0000). Do not assume the two are interchangeable if you parse the response.

If the request changes the applicant's risk level, Sumsub sends the applicantRiskLevelChanged webhook. Unlocking a risk level (same label, no freezeUntil) does not change the level, so no webhook is sent.

Request examples

curl -X PATCH 'https://api.sumsub.com/resources/api/tm/applicants/5e9412223cc1813b4db00000/assessment/riskLevel' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>' \
     -H 'Content-Type: application/json' \
     -d '{
           "label": "High risk",
           "comment": "Escalated by internal fraud review",
           "freezeUntil": "2026-12-31T23:59:59+0000"
         }'

// In this example, `High risk` is the current risk level of the  applicant, and `freezeUntil` is omitted, so the level is unlocked.

curl -X PATCH 'https://api.sumsub.com/resources/api/tm/applicants/5e9412223cc1813b4db00000/assessment/riskLevel' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>' \
     -H 'Content-Type: application/json' \
     -d '{
           "label": "High risk"
         }'

Response explained

The response is the applicant's profile object with the updated assessment. It contains a subset of the fields returned by Get applicant data, (for example, questionnaires, notes, email, and phone are not included). See that page for descriptions of the common fields, such as requiredIdDocs, review, and info.

The fields specific to this method are documented below.

`assessment` attributes

Field	Type	Description
`totalScore`	Float	Total computed risk assessment score for the applicant.
`scores`	Array of objects	Individual scoring-rule results.
`riskLevel`	Object	Currently assigned risk level.
`riskLevelOverride`	Object	Manual/API override of the computed risk level, if any.
`modified`	Object	Audit trail of who last modified the assessment.
`riskLevelFrozen`	Boolean	Computed: `true` if `riskLevelOverride.freezeUntil` is a future date, meaning the risk level is currently locked from recalculation.

`scores[]` element fields

Field	Type	Description
`tag`	String	Applicant tag or scoring rule identifier this score belongs to.
`createdAt`	Date	Date and time when the score was calculated, in the format `YYYY-MM-DD hh:mm:ss+0000` (for example, `2026-08-28 09:00:00+0000`).
`score`	Float	Score contributed by this tag or rule.
`scoreWeight`	Float	Weight applied to this score when computing the weighted total.
`includeInTotalScore`	Boolean	`true` if the score is added to the total risk score. Otherwise, the field is absent.
`txnId`	String	ID of the transaction this score is tied to, if any.
`rules`	Array of objects	Rules that triggered or contributed to this score.
`includeOwnershipPercentage`	Boolean	Defines whether the ownership percentage must be taken into account when calculating the Associated Parties score for this type of beneficiary. ⚠️ Returned only for Associated Parties scores of company applicants.
`aggregateFunction`	String	Aggregate function used when calculating the Associated Parties score. Possible values: `sum` — sums the score across all beneficiaries of this type. `avg` — calculates an average score. `max` — takes the maximum score. ⚠️ Returned only for Associated Parties scores of company applicants.

`rules[]` element fields

Field	Type	Description
`id`	String	ID of the rule.
`name`	String	Internal name of the rule.
`title`	String	Display title of the rule.
`revision`	Integer	Revision number of the rule at the time it was applied.
`tags`	Array of strings	Tags associated with the triggered rule.

`riskLevel` attributes

Field	Type	Description
`label`	String	Display label of the risk level. Not a fixed enum — it is whatever you configured, assigned as part of a workflow or through the API as a signal from your own system.
`styleClass`	String	Color tag associated with this risk level in the Dashboard UI.

`riskLevelOverride` attributes

Field	Type	Description
`freezeUntil`	Date	Date until which the risk level is frozen (locked from automatic recalculation). Returned as `yyyy-MM-dd HH:mm:ss±HHMM` (for example, `2027-05-29 11:59:02+0000`) — see the input format note above. Absent if the override was made without a lock.
`created`	Object	Audit trail of who created this override.
`type`	String (Enum)	How the override was created: `manual` — set via the Dashboard. `api` — set via this method. `workflow` — assigned as part of a specific workflow.

`riskLevelOverride.created` and `assessment.modified` attributes

Field	Type	Description
`date`	Date	Date and time of the action, in the format `YYYY-MM-DD hh:mm:ss` (for example, `2026-08-28 09:53:48`).
`clientSubject`	String	Computed, read-only: the name of who performed the action, as shown to you. May be absent.

Response examples

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

{
  "id": "69bbfe48b8d88e2cd9b00000",
  "createdAt": "2026-03-19 13:46:48",
  "externalUserId": "123-user-id",
  "clientId": "your_cool_id",
  "applicantPlatform": "API",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": ["ID_CARD", "PASSPORT", "RESIDENCE_PERMIT", "DRIVERS"],
        "videoRequired": "disabled"
      }
    ]
  },
  "type": "individual",
  "review": {
    "reviewId": "zWnLM",
    "attemptId": "vzvlC",
    "attemptCnt": 0,
    "levelName": "id-only",
    "createDate": "2026-03-19 13:46:48+0000",
    "startDate": "2026-05-29 11:59:02+0000",
    "reviewReasonCode": "qualityCheck",
    "reviewStatus": "queued",
    "priority": 0
  },
  "info": {
    "firstName": "Bob",
    "firstNameEn": "Bob",
    "lastName": "Dob",
    "lastNameEn": "Dob",
    "country": "DEU",
    "dob": "1982-03-24",
    "idDocs": [
      {
        "idDocType": "ID_CARD",
        "country": "DEU"
      }
    ]
  },
  "assessment": {
    "totalScore": 0.5,
    "scores": [
      {
        "tag": "Tag 1",
        "createdAt": "2026-08-28 09:00:00+0000",
        "score": 0.5,
        "includeInTotalScore": true,
        "txnId": "69bbfe48b8d88e2cd9b000a4",
        "rules": [
          {
            "id": "69bbfe48b8d88e2cd9b000b7",
            "name": "Rule 1",
            "title": "Rule 1",
            "revision": 1,
            "tags": ["Tag 1"]
          }
        ]
      }
    ],
    "riskLevel": {
      "label": "High risk",
      "styleClass": "red"
    },
    "riskLevelOverride": {
      "freezeUntil": "2027-12-31 23:59:59+0000",
      "created": {
        "date": "2026-08-28 09:53:48",
        "clientSubject": "service-prd-<key>-app-<token>"
      },
      "type": "api"
    },
    "modified": {
      "date": "2026-08-28 09:53:48",
      "clientSubject": "Service"
    },
    "riskLevelFrozen": true
  }
}

If the request fails, you will receive an HTTP response containing an error code along with a
message explaining the error. For example, when label does not match a configured risk level:

{
  "code": 400,
  "correlationId": "376973aaee2b7b381830cd779fd3892f",
  "description": "Applicant risk level Test-name level haven't been found in risk level settings"
}

When comment is missing but required:

{
  "code": 400,
  "correlationId": "376973aaee2b7b381830cd779fd3892f",
  "description": "For any risk level override operation except unfreeze comment field should not be empty"
}

Overview

Required permissions

Use case

Notes

Request examples

Response explained

assessment attributes

scores[] element fields

rules[] element fields

riskLevel attributes

riskLevelOverride attributes

riskLevelOverride.created and assessment.modified attributes