# Digital Twin — Data Dictionary

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)

FieldTypeMaxRequiredNotes

sourcestring—yesOriginating system id (e.g. core-banking-system)
eventIdstring (UUID)36yesUsed for idempotency; UUID v4
createdAtUtcinteger (epoch millis)—yesUTC milliseconds; timestamps are timezone-less

Monetary amount

Used wherever a value is posted — transaction / entry APIs (e.g. settlementInfo.amount), balance changes, and limits.

FieldTypeMaxRequiredNotes

amount.valueinteger (64-bit)9,223,372,036,854,775,807yesMinor 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.currencystring3yesISO 4217 or custom stablecoin/crypto code (e.g. USD, BRL, USDC)

The 9,223,372,036,854,775,807 maximum is in minor units. The ceiling in whole currency units depends on the currency's decimals: e.g. USD (2 decimals) ≈ 9.22 × 10¹⁶, whereas an 18-decimal token ≈ 9.22 whole units. Plan accordingly for high-decimal assets.

Account

FieldTypeMaxRequiredNotes

account.branchinteger (32-bit)2,147,483,647yesBranch number
account.accountinteger (64-bit)9,223,372,036,854,775,807yesAccount number
accountTypestring15yesMust match a known account type
timeZonestring30yesIANA name (e.g. America/Chicago)
activeboolean—yesAccount active flag

Account type

FieldTypeMaxRequiredNotes

accountType.keystring15yesUnique account-type identifier
categoryTypestring64yese.g. DEMAND_DEPOSIT, SAVINGS
descriptionstring100yesFree text; stored verbatim

History code (transaction code)

FieldTypeMaxRequiredNotes

historyCodeIdinteger—yesNumeric transaction code (e.g. 3359)
typeenum—yesCREDIT · DEBIT · BALANCE
descriptionstring50yesFree text; stored verbatim

Features (account, account type, history code, membership)

FieldTypeMaxRequiredNotes

feature.namestring64yese.g. BLOCKED_FOR_CREDIT
feature.value.typeenum—yesBOOLEAN · STRING · DECIMAL · DATE · DATE_RANGE
feature.value.stringValuestring1024conditionalWhen type = STRING

Membership / account holder

FieldTypeMaxRequiredNotes

clientIdstring64yesStable hash identifying the client (≤ 64 chars); never the raw tax id
kindstring255yesMembership kind label (e.g. PERSON_HOLDER_TAX_ID)

Hold reason / domain items

FieldTypeMaxRequiredNotes

itemIdstring64yesNatural key of the item (e.g. hold-reason key)
itemDescriptionstring255yesFree text; stored verbatim

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.

← Security & access
REST APIs →