resourceId in customerId when the
account belongs to an uploaded customer.
Upload an account
customerId is nullable because a source may report an account before its owner is known. Set it
only when the source has verified that the account belongs to that customer, using the Customer
resourceId; do not send the customer’s source externalId. A transaction counterparty or
beneficiary association alone is not verified ownership.
accountKind is the provider-neutral category. accountType, identifier type, payment rails,
assets, networks, custody types, and relationship types remain source-defined strings so the
contract can preserve a provider’s vocabulary without adopting that provider’s schema.
On the first POST, omitting accountKind creates the account as OTHER. On a later POST for
the same source identity, omitting accountKind preserves the current kind; it does not silently
change a VIRTUAL_ACCOUNT, wallet, or bank account to OTHER.
Supply a stable sourceExternalId when the source will append another version or use PUT later.
An account with sourceExternalId: null is deliberately unbound: its first observation can be
stored, but no ingestion source can claim it, append another POST version, or update it with
PUT. Upload a new source-bound Account instead when continued source ownership is required.
Use bank for account-holder, institution, beneficiary-address, and routing identifiers. Common
identifier types include ACCOUNT_NUMBER, ROUTING_NUMBER, IBAN, SWIFT_BIC, PIX_KEY,
CLABE, CVU, CBU, BANK_CODE, and BRANCH_CODE. Use wallet for a blockchain network,
address or signature transaction hash, custody type, and account-abstraction flag. A virtual account
can contain bank details and relate to a separately uploaded settlement wallet through
relatedAccounts. An off-ramp wallet can relate to its destination bank account in the same way.
Use bank.recipientRelationship for the source’s relationship classification, such as
FIRST_PARTY. Use bank.beneficiaryIndustry for a structured industry code and identify its
taxonomy in system. These are source facts; Karsa applies separately versioned policy when it
decides whether a relationship or industry combination is unusual.
Keep provider-only fields in customData. Never send private keys, seed phrases, signing secrets,
API credentials, or other authentication material in either accountDetails or customData.
Update an account
Use the Karsa AccountresourceId in the URL. Omitted mutable fields carry forward from the current
snapshot; explicit null clears a nullable field. accountKind and accountType are stable. If
either changes, upload a new Account instead.
documents contains immutable Document versionId values with their role on this account
observation. Omit no contract fields: send null or [] where the API schema allows it.