Compute a behavior score

Request

A server-side call that finalizes the challenge and triggers the scoring engine to analyze the collected behavioral data. Unlike the two SDK endpoints it takes plain JSON with Access Key authentication — no E2E encryption.

transaction_data fields:

Fields marked "encrypted at rest" are automatically encrypted by the server before storage. You should send them in plaintext.

transaction_data is also visible to behavior policies (see Policy decision below). For example, a policy can require a step-up challenge when transaction_amount exceeds a threshold — including on first-session (enrollment) calls.

The is_update parameter

By default, the user's behavioral profile (the enrolled baseline) is maintained automatically: the first session enrolls the baseline, and later sessions refresh it according to the policy configured for your deployment. The optional is_update flag lets your backend override this on a per-call basis.

Once set, is_update takes priority over the default policy-driven behavior at every step. Use false for read-only scoring that must not mutate the profile, and true to force-enroll a known-good session. Omit the field to keep the default behavior — existing integrations need no change.

Read-only scoring (no profile update):

{
  "challenge_id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
  "is_update": false
}

Sample request

{
  "challenge_id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
  "transaction_data": {
    "transaction_id": "txn-001",
    "transaction_timestamp": "2024-01-15T10:30:00Z",
    "transaction_amount": 5000000,
    "currency_code": "VND",
    "transaction_type": "transfer",
    "channel": "mobile_app",
    "account_number": "1234567890",
    "beneficiary_account_number": "0987654321"
  }
}

Response

data.behavior_score carries the verdict and data.risk_level bands it. Scoring follows an enrollment / verification model, like fingerprint enrollment:

• First session (enrollment). The first scored challenge for a (cus_user_id, client) pair builds the user's behavioral baseline. No real scoring takes place — the response is a synthetic safe default (behavior_score: 1000, risk_level: "LOW") carrying more_details.is_first_session: true as the unambiguous marker. Defer first-session risk decisions to your other layers (KYC, device, biometric).
• Subsequent sessions (verification). Each later session is compared against the enrolled baseline. The score answers: "how similar is this session's behavior to the enrolled behavior?"

Calling this endpoint again for an already-scored challenge re-scores it against the current baseline (the call is not idempotent); each call creates its own request_id.

Verification session:

{
  "data": {
    "request_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "behavior_score": 850,
    "risk_level": "LOW",
    "groups": {
      "device_description": { "score": 800, "weight": 0.2 },
      "device_behavior": { "score": 860, "weight": 0.4 },
      "user_behavior": { "score": 855, "weight": 0.4 }
    },
    "explainers": [],
    "server_infos": {}
  }
}

First session — enrollment:

{
  "data": {
    "request_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "behavior_score": 1000,
    "is_fraud": false,
    "risk_level": "LOW",
    "groups": {
      "device_description": { "score": 0, "weight": 0.2 },
      "device_behavior": { "score": 0, "weight": 0.4 },
      "user_behavior": { "score": 0, "weight": 0.4 }
    },
    "is_confident": false,
    "explainers": [],
    "more_details": {
      "is_first_session": true,
      "embedding_count": 1
    }
  }
}

Scoring failure — HTTP 200, data.status: "failure":

{
  "data": {
    "status": "failure",
    "request_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "server_infos": {}
  },
  "errors": [
    {
      "message": "<error description from the scoring engine>",
      "code": "<engine-defined error code>"
    }
  ]
}

Policy decision (decision + evaluation_details)

Deployments can enable a behavior-score policy check per client or access key (configured by TrustVision operators — contact your integration manager to enable it). When enabled, every response — including first-session responses — carries two additional top-level keys next to data:

{
  "data": { "...": "unchanged DS payload as above" },
  "decision": {
    "final_action": "STEP_UP",
    "action_payload": { "challenge_type": "FACE_AUTHEN" }
  },
  "evaluation_details": {
    "applied_policies": [
      {
        "policy_id": "bp_critical_face_authen",
        "policy_name": "CRITICAL risk → Face Authentication",
        "policy_version": "2026.06.04.1",
        "policy_outcome": "OVERRIDDEN"
      }
    ]
  }
}

When no policy matches, final_action falls back to the default mapping from risk_level:

Policies are authored per deployment and can reference the full scoring context, including transaction_data (e.g. "require face authentication when a first-session transaction exceeds 1,000,000 VND").

Backward compatibility: when the policy check is not enabled (the default), neither decision nor evaluation_details is present and the response keeps the legacy data-only shape. Integrations should ignore unknown top-level keys.

Failure codes

Scoring failures (engine-side) return HTTP 200 with data.status: "failure" and engine-defined error codes. Request-validation errors (e.g. no_batch_events, challenge_not_found) return HTTP 4xx/503 with an errors-only body — {"errors": [{"code": "...", "message": "..."}]}, no data block.

The envelope is described under Error Responses, and the codes every Behavioral call can return are listed under Common Error Codes.