API v1.0.0.3

Overview

The TrustVision Behavioral API provides server-side endpoints for device registration, behavioral data collection, and fraud scoring. There are two groups of endpoints:

• Server-side endpoints (/v1/register_device, /v1/behavior/score) — called by your backend using Access Key authentication.
• SDK endpoints (/v1/behavior/create_challenge, /v1/behavior/push_event_batch) — called by the Behavioral SDK from client devices using device-level authentication with end-to-end encryption.

Base URL

https://tv-staging.trustingsocial.com
https://tv.trustingsocial.com

Authentication

Access Key Authentication (Server-side)

Used by: POST /v1/register_device, POST /v1/behavior/score

These endpoints use the standard TrustVision Access Key authentication. Each request must include:

Signature computation:

string_to_sign = HTTP_METHOD + "\n" + URI + "\n" + X-TV-Timestamp + "\n" + Content-MD5
signature = HMAC-SHA256(secret_key, string_to_sign)

Customer User Device Authentication (SDK)

Used by: POST /v1/behavior/create_challenge, POST /v1/behavior/push_event_batch

These endpoints use device-level RSA authentication. Each request must include:

Signature computation:

string_to_sign = HTTP_METHOD + "\n" + URI + "\n" + X-TV-Timestamp + "\n" + encrypted_secret_key + "\n" + Content-MD5
signature = RSA-PSS-SHA256(device_private_key, string_to_sign)

• encrypted_secret_key: A random AES secret key encrypted with the server's RSA public key using RSA-OAEP-SHA256.
• signature: RSA-PSS-SHA256 signature using the device's private key.

End-to-End Encryption (SDK endpoints)

The two SDK endpoints (/v1/behavior/create_challenge, /v1/behavior/push_event_batch) use E2E encryption (the server-side /v1/behavior/score endpoint uses plain JSON with Access Key authentication — no E2E encryption):

• Request body is encrypted with AES-GCM using the secret key from the Authorization header.
• Response body is encrypted with AES-GCM. The response key is encrypted with the device's RSA public key using RSA-OAEP-SHA256, and the response is signed with the server's RSA private key using RSA-PSS-SHA256.

Encrypted response format:

{
  "data": "<AES-GCM encrypted response>",
  "response_key": "<RSA-OAEP encrypted AES key>",
  "signature": "<RSA-PSS-SHA256 signature of response_key + data>"
}

Endpoints

1. Register Device

Register a client device for behavioral data collection. This is a server-side call that creates a customer_user_device record.

Endpoint: POST /v1/register_device

Authentication: Access Key

Request Body

Example request (plain protocol):

{
  "key_pair_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_public_key": "MIIBIjANBgkqhk...",
  "cus_user_id": "user-123",
  "device_id": "device-abc-456"
}

Example request (encrypted protocol):

{
  "key_pair_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_public_key": "<AES-GCM encrypted device public key>",
  "encrypted_secret_key": "<RSA-OAEP encrypted AES key>",
  "cus_user_id": "user-123",
  "device_id": "device-abc-456",
  "protocol": "encrypted"
}

Response

{
  "data": {
    "customer_user_device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "success"
  }
}

2. Create Challenge

Create a behavioral challenge session. The SDK calls this endpoint to initiate a data collection session and receive a challenge ID, nonce, and server public key for E2E encryption.

Endpoint: POST /v1/behavior/create_challenge

Authentication: Customer User Device

Encryption: E2E (request and response are encrypted)

Request Body

Example request (plaintext before encryption):

{
  "session_id": "session-xyz-789"
}

Response

Example response (plaintext before encryption):

{
  "data": {
    "challenge_id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
    "nonce": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "server_public_key": "MIIBIjANBgkqhk..."
  }
}

3. Push Event Batch

Submit a batch of behavioral event data collected by the SDK. Multiple batches can be pushed per challenge, forming a hash chain for integrity verification.

Endpoint: POST /v1/behavior/push_event_batch

Authentication: Customer User Device (with X-Challenge-ID header)

Encryption: E2E (request and response are encrypted)

Request Body

Example request (plaintext before encryption):

{
  "nonce": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "batch_hash": "e3b0c44298fc1c149afbf4c8996fb924",
  "prev_batch_hash": "",
  "seq": 0,
  "data": {
    "events": [
      {
        "type": "touch",
        "timestamp": 1705312200000,
        "x": 150.5,
        "y": 320.0
      }
    ]
  }
}

Response

{
  "data": {
    "status": "success"
  }
}

Note: Batches must be pushed in sequential order. The server verifies the hash chain: each batch's prev_batch_hash must match the previous batch's batch_hash, and sequence numbers must be continuous.

4. Compute Behavior Score

Submit a challenge for behavior scoring. This is a server-side call that finalizes the challenge and triggers the scoring engine to analyze the collected behavioral data.

Endpoint: POST /v1/behavior/score

Authentication: Access Key

How scoring works

Behavioral 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?"

Note: 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.

Request Body

transaction_data fields:

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

Tip: 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.

Controlling profile updates with is_update

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.

Note: 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.

Example — read-only scoring (no profile update):

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

Example 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

Example response (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": {}
  }
}

Example response (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
    }
  }
}

Example response (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>"
    }
  ]
}

Note: 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. See Error Responses.

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 /v1/behavior/score 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.

Integration Flow

The complete behavioral scoring flow involves both server-side and SDK calls:

Your Backend                   SDK (on device)               TrustVision API
     |                              |                              |
     |--- POST /v1/register_device -------------------------------->|
     |<--------------- customer_user_device_id --------------------|
     |                              |                              |
     |--- (pass device credentials to SDK) ----------------------->|
     |                              |                              |
     |                              |-- POST /v1/behavior/         |
     |                              |   create_challenge --------->|
     |                              |<---- challenge_id, nonce,    |
     |                              |       server_public_key -----|
     |                              |                              |
     |                              |-- (collect behavioral data)  |
     |                              |                              |
     |                              |-- POST /v1/behavior/         |
     |                              |   push_event_batch --------->|
     |                              |<---- status: success --------|
     |                              |                              |
     |                              |-- (repeat for more batches)  |
     |                              |                              |
     |--- POST /v1/behavior/score --------------------------------->|
     |<------ behavior_score, risk_level, decision -----------------|

1. Your backend calls POST /v1/register_device to register the user's device and receives a customer_user_device_id.
2. The SDK uses the device credentials to call POST /v1/behavior/create_challenge, which returns a challenge ID, nonce, and server public key.
3. The SDK collects behavioral data (touch, typing, sensors) and pushes batches via POST /v1/behavior/push_event_batch.
4. When the session is complete, your backend calls POST /v1/behavior/score with the challenge ID (and optional transaction_data) to get the behavior score, risk level, and — when the policy check is enabled — the recommended decision.final_action.
5. On the user's first session, step 4 enrolls the behavioral baseline instead of scoring (more_details.is_first_session: true); real scoring starts from the second session.

Error Responses

All endpoints return errors in the following format:

{
  "errors": [
    {
      "message": "description of the error",
      "code": "error_code"
    }
  ]
}

Note: errors[].code is the semantic server error code. On the SDK-authenticated endpoints, the Behavioral SDKs surface this value directly on the error they raise so client code can branch on it: Android TSSessionError.NetworkError.serverErrorCode, iOS ApiError.serverErrorCode, and Flutter PlatformException.details['serverCode'].

Common Error Codes