Integrating
Data dictionary
The data elements exchanged with Digital Twin over AVRO / Kafka messages and REST APIs. The name, type, and maximum size of each field below are the contract — build your payloads within them and your data will be accepted end-to-end across every part of the platform.
Sizes are maximums. Stay within them: a value that respects the size and type here is guaranteed to fit. Strings are UTF-8;
integer means a whole number; enum accepts only the listed values.Message envelope (events)
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
source | string | — | yes | Originating system id (e.g. core-banking-system) |
eventId | string (UUID) | 36 | yes | Used for idempotency; UUID v4 |
createdAtUtc | integer (epoch millis) | — | yes | UTC milliseconds; timestamps are timezone-less |
Monetary amount
Used wherever a value is posted — transaction / entry APIs (e.g. settlementInfo.amount), balance changes, and limits.
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
amount.value | integer (64-bit) | 9,223,372,036,854,775,807 | yes | Minor units, unscaled — e.g. $14.85 → 1485, $12.00 → 1200. The scale (number of decimals) is set by the currency; higher-decimal assets reduce the maximum whole-unit value. |
amount.currency | string | 3 | yes | ISO 4217 or custom stablecoin/crypto code (e.g. USD, BRL, USDC) |
Account
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
account.branch | integer (32-bit) | 2,147,483,647 | yes | Branch number |
account.account | integer (64-bit) | 9,223,372,036,854,775,807 | yes | Account number |
accountType | string | 15 | yes | Must match a known account type |
timeZone | string | 30 | yes | IANA name (e.g. America/Chicago) |
active | boolean | — | yes | Account active flag |
Account type
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
accountType.key | string | 15 | yes | Unique account-type identifier |
categoryType | string | 64 | yes | e.g. DEMAND_DEPOSIT, SAVINGS |
description | string | 100 | yes | Free text; must not contain personal data |
History code (transaction code)
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
historyCodeId | integer | — | yes | Numeric transaction code (e.g. 3359) |
type | enum | — | yes | CREDIT · DEBIT · BALANCE |
description | string | 50 | yes | Free text; must not contain personal data |
Features (account, account type, history code, membership)
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
feature.name | string | 64 | yes | e.g. BLOCKED_FOR_CREDIT |
feature.value.type | enum | — | yes | BOOLEAN · STRING · DECIMAL · DATE · DATE_RANGE |
feature.value.stringValue | string | 1024 | conditional | When type = STRING |
Membership / account holder
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
clientId | string | 64 | yes | Stable hash identifying the client (≤ 64 chars); never the raw tax id |
kind | string | 255 | yes | Membership kind label (e.g. PERSON_HOLDER_TAX_ID) |
Hold reason / domain items
| Field | Type | Max | Required | Notes |
|---|---|---|---|---|
itemId | string | 64 | yes | Natural key of the item (e.g. hold-reason key) |
itemDescription | string | 255 | yes | Free text; must not contain personal data |
These field specs apply to both the AVRO message payloads and the REST request bodies — see REST APIs and AVRO / Kafka messages for the full operations. Machine-readable docs for AI agents: llms.txt.