Accounts API

The Accounts API manages financial investment accounts (brokerage and custodial accounts) on the Altafid platform. It covers account discovery, linking accounts to the platform and to households, multi-currency balances and performance, holdings and transactions, and tenant- and household-level aggregation for dashboards.

Authentication and headers

All endpoints below require the standard gateway headers. x-tenant-uuid is mandatory and scopes every request to a single tenant.

Linking flow

Newly ingested accounts arrive unlinked. To surface an account in reporting you link it to the platform, then map it to a household. Analytics endpoints become meaningful once an account is linked.

Account endpoints

List endpoints accept page (zero-indexed, default 0) and size (default 20) and return a PagedResponse. The transactions endpoint sorts on executeDate (default), snapshotDate, transactionType, grossAmount, or accountNumber via sortColumn + sortOrder.

curl "https://api.altafid.dev.altafid.net/api/accounts/unlinked?keyword=12345&page=0&size=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-type: TENANT_STAFF"

Linking and households

Use the link-state endpoint to attach an account to the platform, then map it to a household. Each mapping is one-to-one.

Account analytics

Per-account analytics for a single linked account. When a date range is omitted, the service uses startDate = linkDate and endDate = today.

Household aggregation

Roll up the accounts mapped to a household.

Tenant aggregation

Roll up every linked account in the tenant.

Workstation

The workstation endpoints power the advisor dashboard: filtered grids and chart aggregates across accounts, households, and contacts. Filter requests support quintile buckets (values 1–5) for MTD, QTD, and YTD returns and for EOD balances, plus an optional staffUuid scope.

Grids

Charts

POST /api/accounts/workstation/charts, .../household/charts, and .../contact/charts accept a WorkstationChart request (metric = BALANCE | MTD | QTD | YTD; currency required when metric=BALANCE).

Account detail aggregates

The POST /api/accounts/workstation/account/* family returns specific aggregates for a set of accounts over a date window (WorkstationAccount request: startDate, endDate, optional accountUuids):

The POST /api/accounts/workstation/household/* family mirrors these for households (WorkstationHousehold request: startDate, endDate, optional householdUuids): asset-allocation-pie-chart, asset-allocation-detailed, balance-line-chart, balance-line-chart-summary, performance-line-chart, performance-line-chart-summary, and household-summary.

Securities classification

Admin endpoints for classifying the share-class FIGIs held across the tenant's accounts.

Audit

POST/api/accounts/audit returns a paginated, filterable log of link/unlink events.

{
  "householdUuids": ["H019..."],
  "accountUuids":   ["A019..."],
  "events":         ["ACCOUNT_LINKED_HOUSEHOLD", "ACCOUNT_UNLINKED_HOUSEHOLD"],
  "startDate":      "2026-01-01",
  "endDate":        "2026-05-31"
}

Query params: sortColumn (id, householdUuid, accountUuid, event, createdAt — default createdAt), sortOrder (asc/desc), page, size. Returns PagedResponse<AccountAudit>.

Data model

PagedResponse

Standard pagination envelope: content[], page, size, totalElements, totalPages.

AccountSummary

Returned by the unlinked list. Core account attributes.

AccountDetailedSummary

Returned by the linked list and single-account detail. Includes everything in AccountSummary plus portfolio/manager attribution, snapshotDate, trading, distinctFxCurrencies, and current/previous EOD balances, net deposits, day change, and gain/loss in USD, CLP, and EUR.

Transaction

Fields: accountUuid, accountNumber, snapshotDate, executeDate, transactionType, description, actionCode, pricePerShare, grossAmount, custodian, fxCurrency, fxRate, transactionQuantity, executePrice, and the CLP/USD conversions (executePriceClp, pricePerShareClp, grossAmountClp, executePriceUsd, pricePerShareUsd, grossAmountUsd).

AccountPosition

Holding for the latest snapshot: name, ticker, price, rank, quantity, market value in USD/CLP/EUR/CAD/GBP, fxCurrency, reinvestDividend, ppShareClassFigi, fsShareClassFigi, countryCode.

AccountAllocation & AssetClass

Classification breakdown: level1Classification plus total market value and percentage in USD, CLP, and EUR.

AccountFxRate

conversionDate, fxCurrency, fxCurrencyInUsd, usdInFxCurrency.

AccountsListSummary / HouseholdAccountsSummary

Aggregate roll-up: accountCount, householdBaseCurrency, total assets, beginning/ending value, net deposits, change in value, and gain/loss across USD, CLP, and EUR. HouseholdAccountsSummary adds householdUuid.

AccountAudit

tenantUuid, householdUuid, householdName, accountNumber, accountUuid, event (AccountAuditEvent), createdAt.

Request bodies

Enum reference

The following fields accept a fixed set of values. Pass the exact string value shown.

linkState

AccountAuditEvent

workstation chart metric

currency

performance / balance period labels