Evaluate endpoint
POST <base-url>/v1/engine/evaluateContent-Type: application/jsonX-API-Key: <api-key>X-Signature-Version: v2X-Timestamp: <current-iso-8601-timestamp>X-Request-ID: <fresh-uuid>X-Signature: <hmac-sha256-hex>Submit the request before funds move and wait for the synchronous decision. The core-evaluation target is under 350 ms, excluding network latency and post-response processing.
Authentication
Section titled “Authentication”Sign the exact request-body bytes with HMAC-SHA256. See Authentication and HMAC for the canonical algorithm and complete language examples.
Headers
Section titled “Headers”| Header | Required | Constraints | Description |
|---|---|---|---|
Content-Type |
Yes | application/json |
Media type for the serialized body. |
X-API-Key |
Yes | Supplied by Vantrace | Authenticates the tenant. |
X-Signature-Version |
Yes | v2 |
Selects the version 2 signing contract. |
X-Timestamp |
Yes | Current ISO 8601 time; within five minutes | Replay-window protection. |
X-Request-ID |
Yes | Fresh UUID for every request | Traces one request attempt. |
X-Signature |
Yes | HMAC-SHA256 hex | Signature of the exact raw body bytes using the tenant’s HMAC secret. |
Request schema
Section titled “Request schema”Top-level body
Section titled “Top-level body”| Field | Type | Required | Nullable | Default | Description |
|---|---|---|---|---|---|
transaction |
object | Yes | No | — | The transaction being evaluated. |
customer |
object | Yes | No | — | The bank customer associated with the account under evaluation. |
account_snapshot |
object | No | No | Omitted | Privacy-safe facts about the evaluated bank-owned account. Recommended when available. |
context |
object | No | No | Omitted | CBS-supplied real-time context, including current_balance. Historical and behavioural fields are derived by Vantrace. |
transaction
Section titled “transaction”| Field | Type | Required | Nullable | Constraints / allowed values | Default |
|---|---|---|---|---|---|
reference_id |
string | No | No | Stable client reference; not an idempotency key | — |
amount |
number | Yes | No | Greater than 0; major currency units |
— |
currency |
string | No | No | ISO 4217 three-letter code | NGN |
trx_type |
string | Yes | No | Integration-approved type, such as transfer, deposit, withdrawal |
— |
channel |
string | Yes | No | Such as mobile_app, USSD, POS, ATM, teller, online |
— |
txn_direction |
enum | Yes | No | inbound, outbound |
— |
is_cash |
boolean | No | No | Physical cash or approved cash-equivalent only | false |
is_cross_border |
boolean | No | No | — | false |
source_account_id |
integer | Yes | No | True originating-account identifier | — |
evaluated_account_id |
integer | No | No | Bank-owned account under review | — |
beneficiary_account_id |
integer | No | No | Receiving account, when known | — |
counterparty_name |
string | No | No | Send only when required | — |
counterparty_bank_code |
string | No | No | Counterparty institution code | — |
narration |
string | No | No | Avoid unnecessary personal data | — |
geo_lat |
number | No | No | Transaction latitude when lawfully collected | — |
geo_long |
number | No | No | Transaction longitude when lawfully collected | — |
status |
string | No | No | Integration-approved status | completed |
transaction_timestamp |
string | No | No | ISO 8601 date-time | Server receive time |
customer
Section titled “customer”| Field | Type | Required | Nullable | Constraints / allowed values | Default |
|---|---|---|---|---|---|
customer_id |
string | Yes | No | Stable identifier; numeric inputs are normalized to strings | — |
entity_type |
enum | Yes | No | individual, corporate |
— |
kyc_tier |
integer | Yes | No | 1 to 3 |
— |
is_pep |
boolean | No | Yes | CBS-supplied PEP status | Vantrace-resolved when empty |
sanctions_flag |
boolean | No | Yes | CBS-supplied sanctions status | Vantrace-resolved when empty |
adverse_media_flag |
boolean | No | Yes | CBS-supplied adverse-media status | Vantrace-resolved when empty |
is_shell_company |
boolean | No | Yes | Non-null CBS values, including false, are used and saved |
Stored database value; otherwise null |
has_complete_cdd |
boolean | No | Yes | Non-null CBS values, including false, are used and saved |
Stored database value; otherwise null |
kyc_last_reviewed_at |
string | No | No | ISO 8601 date-time | — |
The CBS supplies is_pep, sanctions_flag, and adverse_media_flag. Vantrace retains each supplied value and resolves a value from its screening data only when that CBS field is empty.
For is_shell_company and has_complete_cdd, Vantrace applies this precedence:
- A non-null CBS value is used and saved.
falseis a valid value and is not treated as empty. - When the field is omitted or
null, Vantrace falls back to the stored database value without replacing it. - When neither the CBS nor the database has a value, the field remains
null, meaning unknown.
account_snapshot
Section titled “account_snapshot”account_snapshot supplies privacy-safe facts for the bank-owned account being evaluated.
| Field | Type | Required | Nullable | Constraints / allowed values | Default |
|---|---|---|---|---|---|
account_id |
integer | Yes | No | Must match the evaluated bank-owned account | — |
open_ts |
string | No | No | ISO 8601 date-time | — |
last_activity_ts |
string | No | No | ISO 8601 date-time before this transaction | — |
balance |
number | No | No | Current caller-known balance | — |
account_type |
string | Yes | No | Such as savings, current, loan |
— |
currency |
string | No | No | ISO 4217 three-letter code | NGN |
Unknown properties are rejected. Use the documented names exactly: open_ts, last_activity_ts, balance, and currency.
{ "account_id": 41001, "open_ts": "2024-06-20T08:30:00Z", "last_activity_ts": "2026-09-28T09:55:00Z", "balance": 480000.00, "account_type": "savings", "currency": "NGN"}context
Section titled “context”| Field | Type | Required | Nullable | Constraints / allowed values | Default |
|---|---|---|---|---|---|
current_balance |
number | No | No | Current CBS balance for the evaluated account at request time | — |
current_balance comes from the CBS. Vantrace uses the supplied value as the current account balance and does not derive or replace it.
Only send other real-time context fields agreed for your integration. Do not reconstruct Vantrace’s historical transaction windows or behavioural calculations.
Examples of client-supplied signals that may be supported include current balance, counterparty screening matches, device relationships, jurisdiction indicators, and proliferation-financing indicators. Availability depends on the integration contract and enabled rules.
See Data ownership for the values supplied by the CBS and the values Vantrace derives.
Example request
Section titled “Example request”See the copy-paste runnable 5-minute Quickstart and richer worked examples.