TruvaLI API Documentation

Integration interface for fraud prevention, AML monitoring and customer onboarding (KYC) services.

Overview

All endpoints are served under the /api/ prefix and speak JSON (except document upload endpoints, which use multipart/form-data). Request bodies must be UTF-8 encoded.

Endpoint list

Authentication

You obtain an access token using your API key and secret key.

Request

{
  "api_key": "05b190fb-c354-4431-bf04-450cf77e0306",
  "api_secret": "9d4f2a11-77c3-4b2e-9a51-1f0b8c3d7e42"
}

Response | 200

{
  "status": true,
  "message": "Login successful.",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Usage in subsequent requests

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Errors

Token check

Tests whether the token you have is still valid. Only callable via GET; a POST request returns 403 due to CSRF protection.

{
  "status": true,
  "message": "Token is valid for Example Customer.",
  "data": {
    "client": "Example Customer",
    "session_id": "8f2c1a90-3b7e-4d55-9c21-6a4b8e0d1f33"
  }
}

Response format

All JSON endpoints use the same envelope:

{
  "status":  true | false,     // whether the request as a whole succeeded
  "message": "a human-readable summary",
  "data":    { ... }           // endpoint-specific content
}

Error model

There are two different error levels, and distinguishing between them matters for integration.

1. Request level: the entire request is rejected

If the body is malformed, no record is processed and 4xx is returned. This points to a programming error on the caller's side.

2. Record level: only that record is skipped

If the body format is correct but a record's content is invalid, only that record is dropped, the others continue to be processed, and the request returns 200. The skipped record is flagged with action: "skipped" and error.

{
  "status": true,
  "message": "Processed 3 financial event record(s).",
  "data": {
    "results": [
      { "transaction_ref": "TX-1", "id": "…", "action": "created",  "score": 0,   "decision": "ACCEPT" },
      { "transaction_ref": "TX-2", "id": null, "action": "skipped",
        "error": "'amount' cannot be negative (got -1.00); use io_type to express direction.",
        "score": 100.0, "decision": "REJECT" },
      { "transaction_ref": "TX-3", "id": "…", "action": "created",  "score": 0,   "decision": "ACCEPT" }
    ]
  }
}

3. Warnings: the record is processed but something was corrected

Correctable deviations do not drop the record; the value is normalized and reported via warnings. We recommend monitoring these warnings and fixing them at the source.

{
  "transaction_ref": "TX-4",
  "action": "created",
  "warnings": [
    "'currency' was normalised to upper case ('usd' -> 'USD').",
    "'amount' was rounded to 2 decimal places (1.129 -> 1.13)."
  ]
}

Batch requests

All upsert endpoints accept either a single object or an array of objects. Up to 1000 records can be sent per request.

// single record
{ "customer_ref": "C-1001", "first_name": "Jane" }

// batch
[
  { "customer_ref": "C-1001", "first_name": "Jane" },
  { "customer_ref": "C-1002", "first_name": "John" }
]

In both cases, the response returns an array inside data.results, and the order matches the order you sent.

Customer upsert

Creates or updates a customer record. The record is matched by customer_ref; a second call with the same reference performs an update. After it is saved, the customer is run through the rule engine and a risk score is calculated.

Fields

Corporate customer fields

Available in addition when you send customer_type: 2:

Example request

POST /api/customer/upsert/
Authorization: Bearer <token>
Content-Type: application/json

{
  "customer_ref": "C-1001",
  "customer_type": 1,
  "first_name": "Jane",
  "last_name": "Smith",
  "gender": "female",
  "birth_date": "1990-04-17",
  "identity_number": "10000000146",
  "nationality": "TUR",
  "email": "[email protected]",
  "phone": "+905301234567",
  "ip_address": "88.230.14.7",
  "registration_date": "2026-01-15T09:30:00Z",

  "loyalty_tier": "gold",
  "internal_segment": "vip"
}

The last two fields are not defined in the model; they are not rejected, they are stored in the record's raw field and can be used when writing rules.

Example response | 200

{
  "status": true,
  "message": "Processed 1 customer record(s).",
  "data": {
    "results": [
      {
        "customer_ref": "C-1001",
        "id": "3f1c8a20-9d44-4e77-b1a2-77c9e0b34512",
        "action": "created",
        "score": 25.0,
        "decision": "ACCEPT",
        "sanction_score": 0,
        "sanction_topic": [],
        "ip_address_score": 12.5,
        "email_risk_score": 34.0,
        "warnings": []
      }
    ]
  }
}

Financial transaction upsert

Reports transactions that involve a movement of funds. The record is matched by transaction_ref; a second call with the same reference performs an update.

Fields

Example request

POST /api/transaction/financial/upsert/
Authorization: Bearer <token>
Content-Type: application/json

{
  "customer_ref": "C-1001",
  "event_slug": "deposit",
  "transaction_ref": "TX-2026-0007781",
  "amount": "15750.00",
  "currency": "TRY",
  "io_type": 0,
  "payment_method": "credit_card",
  "event_date": "2026-08-07T11:42:13Z",
  "source_address": "TR330006100519786457841326",
  "ip_address": "88.230.14.7",
  "channel": 1,
  "metadata": { "campaign": "summer26" }
}

Example response | 200

{
  "status": true,
  "message": "Processed 1 financial event record(s).",
  "data": {
    "results": [
      {
        "transaction_ref": "TX-2026-0007781",
        "id": "6b708204-81d2-49e2-a808-cbc9beae549b",
        "action": "created",
        "score": 40.0,
        "decision": "REVIEW",
        "rule_check": true,
        "log_id": "b1e7…",
        "warnings": []
      }
    ]
  }
}

Non-financial transaction upsert

Reports events that do not involve a movement of funds, such as login attempts, password changes, IBAN registration, or profile updates.

The field set is the same as the financial endpoint's; there are no amount- or currency-related fields. If you send these fields anyway, they are not rejected; they are written to the record's raw field but not processed.

Example request

POST /api/transaction/non-financial/upsert/
Authorization: Bearer <token>
Content-Type: application/json

{
  "customer_ref": "C-1001",
  "event_slug": "failed_login",
  "transaction_ref": "EVT-2026-0004412",
  "event_date": "2026-08-07T11:40:02Z",
  "event_description": "Incorrect password, attempt 3",
  "ip_address": "185.66.12.9",
  "device_id": "a91f3c7d20e4",
  "channel": 3
}

Document verification (KYC) | Flow overview

The customer onboarding flow consists of five steps:

1. Create session (server-to-server). Your platform calls create-session with a Bearer token and receives a session token (endpoint_token).
2. Redirect to the end user. You pass the session token to the end user's browser. From this point on, document upload calls are made with this token; your API key never reaches the device.
3. Document upload. The end user uploads the documents required by the flow using upload_document.
4. Video call (if the flow requires it). An agent joins the call, and a snapshot is captured if needed.
5. Resolution. The session is closed with end-kyc-session and the operator makes a decision.

Flow definition (flow)

Which documents to collect, whether a video call is required, and where the result notification should be sent are all kept in the flow definition. Flows are created from the admin panel and referred to by a code (e.g. onboarding). You send this code when creating a session.

A flow determines the following:

• Checklist: which document types are required
• Video call: if the checklist includes recording or snapshot, a call is set up; otherwise none is set up at all
• Automatic decision: whether the session is approved without waiting for an operator once all steps complete successfully
• Time limit: how many minutes the flow must be completed within

Create session

Opens a KYC session, or returns the already-open session for the same customer and flow.

Fields

Example request

POST /api/document/create-session/
Authorization: Bearer <token>
Content-Type: application/json

{
  "customer_ref": "C-1001",
  "flow": "onboarding",
  "device_id": "a91f3c7d20e4",
  "ip_address": "88.230.14.7",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) …",
  "geo": { "lat": 41.0082, "lon": 28.9784 }
}

Example response | 200

{
  "status": true,
  "message": "Processed verification session record.",
  "data": {
    "session": {
      "session_id": "1aa3d05c-fde7-410c-b0e1-090487760c47",
      "flow": "onboarding",
      "required_artifact_types": ["doc_front", "doc_mrz", "selfie"],
      "pending_artifact_types":  ["doc_mrz", "selfie"],
      "succeeded_artifact_types": ["doc_front"],
      "requires_video_call": false,
      "attempt_no": 1,
      "livekit_token": "",
      "endpoint_token": "eyJjdXN0b21lcl9yZWYiOiJDLTEwMDEi…",
      "mrz_data": null
    }
  }
}

Errors

Upload document

Called from the end user's browser. Authentication is established with the endpoint_token you received from create-session.

Form fields

Example request

const formData = new FormData();
formData.append('token', endpointToken);
formData.append('artifact_type', 'doc_front');
formData.append('snapshot', file);

await fetch('/api/document/upload_document/', {
    method: 'POST',
    body: formData      // DO NOT manually add the Content-Type header
});

Response | 200

{
  "status": "success",
  "path": "snapshots/2026-08-07/1aa3d05c…__985545f0….jpg",
  "artifact_id": "744a654d-3350-4f13-8de7-2f88d888e739",
  "artifact_type": "doc_front"
}

Errors

The error body uses the standard envelope:

{
  "status": false,
  "message": "This verification session is closed (decided).",
  "data": { "reason": "session_closed" }
}

Take snapshot

Saves the frame captured from the end user's camera during the video call. Requires the same token as upload_document; the document type is automatically assigned as snapshot.

{
  "status": "success",
  "path": "snapshots/2026-08-07/1aa3d05c…__985545f0….jpg",
  "artifact_id": "744a654d-3350-4f13-8de7-2f88d888e739"
}

Error codes are the same as upload_document.

End session

Ends the call and writes the checklist marked by the agent to the audit record.

Request

Response | 200

{
  "status": true,
  "session_id": "1aa3d05c-fde7-410c-b0e1-090487760c47",
  "session_status": "completed"
}

An undefined status value is rejected with 400; it is never silently treated as "failed". Closing an already-closed session again is not an error (page reload, double click).

How it works

Document verification runs asynchronously. The upload_document call only tells you "file received"; operations such as OCR, MRZ reading and face matching run in the background and can take a few seconds.

You don't need to keep polling to wait for the result: as soon as each verification finishes, a websocket message is sent to the relevant session.

document uploaded  →  background verification  →  websocket message  →  your UI

Connection and registration

After opening the websocket connection, you need to send a registration message indicating which session you are listening to. The endpoint_token you received from create-session is used as identity, the same token as the document upload endpoints.

const ws = new WebSocket("wss://<websocket-host>/document/");

ws.onopen = () => {
    ws.send(JSON.stringify({
        event: "register",
        token: endpointToken        // endpoint_token from create-session
    }));
};

ws.onmessage = (e) => {
    const msg = JSON.parse(e.data);
    if (msg.event !== "broadcast") return;

    const { type, result } = msg.data;
    if (result.code === "success") {
        // mark the step as completed
    } else {
        // ask the user to retry: result.message
    }
};

Result messages

Message envelope

Every incoming message has the same structure:

{
  "event": "broadcast",
  "client_id": "...",
  "timestamp": 1786111190365,        // epoch, milliseconds
  "correlation_id": "9f3c1a20-…",    // to track a single notification
  "data": {
    "to": "1aa3d05c-fde7-410c-b0e1-090487760c47",   // session id
    "delivery": "transporter",
    "type": "mrz_verification_result",              // which verification
    "result": {
      "code": "success",                            // success | fail
      "data": { … },                                // extra data, null if none
      "message": "MRZ text has been successfully read."
    }
  }
}

Message types

Example: successful MRZ read

{
  "event": "broadcast",
  "timestamp": 1786111190365,
  "correlation_id": "9f3c1a20-4b77-4e51-8a03-2d5e91c4f8a1",
  "data": {
    "to": "1aa3d05c-fde7-410c-b0e1-090487760c47",
    "delivery": "transporter",
    "type": "mrz_verification_result",
    "result": {
      "code": "success",
      "data": {
        "first_name": "AYSE",
        "last_name": "YILMAZ",
        "document_number": "A12B34567",
        "birth_date": "1990-04-17",
        "expiry_date": "2031-06-30",
        "nationality": "TUR"
      },
      "message": "MRZ text has been successfully read."
    }
  }
}

Example: failed face match

{
  "event": "broadcast",
  "timestamp": 1786111203881,
  "correlation_id": "c07be413-1f9a-42d0-9c62-b8ad5e3a7710",
  "data": {
    "to": "1aa3d05c-fde7-410c-b0e1-090487760c47",
    "delivery": "transporter",
    "type": "face_verification_result",
    "result": {
      "code": "fail",
      "data": null,
      "message": "Yüzler eşleşmedi, lütfen tekrar deneyin."
    }
  }
}

Handling recommendations

• Don't rely on ordering. Verifications finish in different processes and at different speeds; messages can arrive in a different order than the upload order. Handle every message based on its type field.
• Ignore type values you don't recognize. New verification steps may be added in the future; an unknown type should never break your UI.
• Don't treat the websocket as the single source of truth. The connection can drop. You can always get the definitive state by calling create-session again: the succeeded_artifact_types and pending_artifact_types in the response reflect the truth at that moment.
• The same message can arrive more than once. If the user re-uploads a document, a new result message is produced for that type. You can tell duplicates apart with correlation_id.

Constants

Document types (artifact_type)

Customer type (customer_type)

Gender (gender)

Transaction direction (io_type)

Channel (channel)

Decision (decision)

Event type (event_type)

Selected when defining an event in the admin panel; determines which endpoint it is sent to.

Error codes

KYC endpoints include a data.reason field in their error bodies. These codes are stable and can be used safely in code; the message text may change.