Reporting standard
JSON and XLSX format for portfolio holdings, transactions, prices and results
Edition 1.6.4 (9 April 2026)
Contact: support@trackrecords.app
The standard is the file (or API payload) TrackRecords uses to load a book, recalculate TWR/MWR, run contribution and attribution, and apply limits and risk. Field names are English. You can send JSON (preferred in production) or XLSX (convenient while testing).
A file may contain any combination of sections. Holdings plus results are enough to inspect composition and the manager’s own figures. Transactions and prices are required to recalculate return and contribution.
| Section | Purpose |
|---|---|
| meta | Portfolio identity, base currency, report period |
| portfolio | Holdings on a date (structure, quantity, dirty price, value) |
| instruments | Non-listed assets: deposits, receivables, repo, loans, property |
| transactions | Cash, security and debt movements: not trades only |
| prices | Valuation prices under the client accounting policy |
| results | Manager-reported income, TWR/MWR, fees, NAV |
| nav | NAV and external flows, used for TWR/MWR at portfolio level |
Encoding: UTF-8. Large files may be uploaded as ZIP.
meta
| Column | Description | Type |
|---|---|---|
| portfolio_name* | Display name | string |
| description | Comment | string |
| owner | Asset owner / client | string |
| manager | Manager, broker or fund | string |
| portfolio_id | Mandate, account or other id | string |
| portfolio_type | 2 snapshot, 3 transaction-based | int32 |
| currency* | Base currency, ISO 4217 | string |
| reported_date* | Report date, yyyy-mm-dd | date |
| start_date* | Period start, yyyy-mm-dd | date |
| created_at | File created | date |
* Required
portfolio (holdings on a date)
Holdings support structure, risk and stress. They do not by themselves produce a time-weighted return.
| Column | Description | Type |
|---|---|---|
| stated_at* | Holdings date | date |
| partition_id | Lot / parcel id | string |
| account_number | Broker or bank account (required for cash) | string |
| asset_class* | Class name from the catalogue below | string |
| asset_class_id* | Class id | int32 |
| code_type* | ISIN, INSTRUMENT or CASH | string |
| code* | Identifier for that type | string |
| asset_name | Name | string |
| quantity* | Quantity | decimal |
| price_dirty* | Unit dirty price (negative for payables) | decimal |
| price_dirty_currency* | Price currency, ISO 4217 | string |
| currency_rate* | price_dirty_currency / portfolio currency | decimal |
| value_in_portfolio_currency* | price_dirty × currency_rate × quantity | decimal |
| price_type | 0 hold-to-maturity, 1 fair value (default) | int32 |
| pif | Fund name for look-through | string |
Identity: value_in_portfolio_currency = quantity × price_dirty × currency_rate (rule 11, rounded to 2 dp).
Asset classes
| Category | asset_class | id |
|---|---|---|
| Equity | Equities | 10 |
| Equity | Mortgage certificates | 22 |
| Equity | Funds | 26 |
| Equity | ETF | 42 |
| Equity | REIT | 43 |
| Equity | ADR/GDR | 49 |
| Bonds | Corporate bonds | 1 |
| Bonds | Covered / mortgage bonds | 2 |
| Bonds | Regional bonds | 3 |
| Bonds | Municipal bonds | 31 |
| Bonds | Foreign sovereign bonds | 4 |
| Bonds | Sovereign bonds | 5 |
| Bonds | Eurobonds | 6 |
| Bonds | Bonds | 7 |
| Bonds | Structured bonds | 9 |
| Cash and deposits | Deposits | 11 |
| Cash and deposits | Cash at broker | 12 |
| Cash and deposits | Cash at bank | 13 |
| Cash and deposits | Cash in clearing margin | 23 |
| Cash and deposits | Subordinated deposits | 38 |
| Repo | Repo receivables | 19 |
| Repo | Repo payables | 20 |
| Receivables / payables | Other receivables | 17 |
| Receivables / payables | Receivables | 18 |
| Receivables / payables | Payables | 28 |
| Receivables / payables | Other payables | 30 |
| Property | Residential property | 15 |
| Property | Commercial property | 16 |
| Property | Land | 25 |
| Derivatives | Futures | 34 |
| Derivatives | Options | 39 |
| Derivatives | Interest-rate swap | 40 |
| Derivatives | FX swap | 41 |
| Expenses | Administrative and other expenses | 36 |
| Expenses | Manager remuneration | 37 |
| Other | Indices | 35 |
| Other | Loans | 14 |
| Other | MFO securities | 21 |
| Other | Other assets | 24 |
| FX | Currency pairs | 44 |
| FX | Cryptocurrency | 45 |
| Rates | Rates and indicators | 46 |
| Rates | Macro indicators | 47 |
| Commodities | Exchange-traded commodities | 48 |
Listed equities, bonds and funds are resolved from the TrackRecords reference database by ISIN (or another public code). Everything else belongs in instruments.
instruments
| Column | Description | Type |
|---|---|---|
| stated_at* | Record date | date |
| asset_class | Class name | string |
| asset_class_id* | Class id | int32 |
| instrument_code* | Unique code (account number for cash) | string |
| asset_name | Name | string |
| inn* | Issuer tax id or a unique numeric code | string |
| currency* | ISO 4217 | string |
| start_date | Interest start | date |
| maturity_date | Maturity | date |
| nominal | Face in instrument currency | decimal |
| yield_or_dividend_rate | Rate, % p.a. | decimal |
| yield_or_dividend_freq | 0 at maturity, 1 annual, 2 semi, 4 quarterly, 12 monthly | int32 |
| collateral | Collateral in instrument currency | decimal |
Deposits and repo must fill start_date, maturity_date, nominal, yield_or_dividend_rate, yield_or_dividend_freq.
results
Optional. Lets you compare the manager’s own income, TWR/MWR and fees with TrackRecords.
| Column | Description | Type |
|---|---|---|
| period_id | Row number | int32 |
| period_name | e.g. YTD, 2024 | string |
| partition_id | Lot id | string |
| start_date / end_date | Period | date |
| income_currency | ISO 4217 | string |
| income_gross / income_net | Income before / after fees | decimal |
| mwr_gross / mwr_net | Money-weighted return, simple % | decimal |
| twr_gross / twr_net | Time-weighted return, simple % | decimal |
| start_nav / end_nav | NAV | decimal |
| inflows / outflows | External flows | decimal |
| avg_nav / aic | Average NAV / invested capital | decimal |
| management_fees / success_fees / other_fees | Fees | decimal |
nav
TWR and MWR at portfolio level. Prefer a point on every day of the period. Minimum: start, end, and every external-flow date.
| Column | Description | Type |
|---|---|---|
| partition_id | Lot id | string |
| date* | yyyy-mm-dd | date |
| nav* | NAV in currency | decimal |
| net_flows* | External inflows minus outflows | decimal |
| currency* | ISO 4217 | string |
transactions
One table for cash, securities and debt. A transaction is any change in those balances: not only a trade.
Sign convention: securities, money and debt are balance changes. Minus = outflow / disposal. Plus = inflow. A share sale has negative securities and positive money.
| Field | Description | Required |
|---|---|---|
| partition_id | Lot id | |
| account_number | Account (required for cash movements) | if money ≠ 0 |
| transaction_currency* | ISO 4217 | if money or debt ≠ 0 |
| currency_rate | FX rate on the transaction | |
| date_transaction* | Trade / event datetime | yes |
| date_settlement | Settlement datetime | |
| transaction_id* | Unique id | yes |
| connected_transaction_id | Linked id (repo legs) | |
| code_type* | ISIN / INSTRUMENT / CASH | yes |
| code* | Instrument or ISO currency for cash | yes |
| transaction_type* | See catalogue | yes |
| securities* | Security quantity change | |
| money* | Cash change | |
| debt* | Receivable / payable change | |
| comment | Text | |
| exchange_id | Venue id from the TrackRecords catalogue | |
| fee_category | For fee: depositary, brokerage, exchange, bank, management, success | |
| other | Extra JSON | |
| price_type | 0 HTM, 1 fair value |
Uniqueness inside a portfolio: code_type + transaction_type + transaction_id + account_number + fee_category + partition_id.
transaction_type
| id | name | Meaning |
|---|---|---|
| 1 | trade | Buy/sell securities or futures. Direction is the sign of securities / money |
| 2 | dividend | Dividends / fund distributions |
| 3 | interest | Deposit and repo interest |
| 4 | coupon | Bond coupons |
| 5 | maturity | Bond redemption proceeds |
| 6 | amortisation | Partial principal repayment |
| 7 | deposit | Deposit open/close |
| 8 | margin | Variation margin |
| 9 | forex | FX with actual cash delivery |
| 10 | transfer_internal | Transfer between accounts in the same book |
| 11 | transfer_external | External transfer (also used for opening balances) |
| 12 | fee | Bank, broker, exchange, depositary, manager |
| 13 | other | Unclassified |
| 14 | repo_l1 | Repo first leg |
| 15 | repo_l2 | Repo second leg |
| 16 | debt | Accrue / write off receivables or payables |
| 17 | cash_interest | Interest on cash balances |
| 18 | split | Share split (securities = new minus old quantity) |
| 19 | consolidation | Reverse split |
How to book common events
Buy securities. Positive securities, negative money. Do not send a trade price: it is money / securities. Accrued interest sits in the dirty cash amount or in a separate row.
Opening balances without a full history: transfer_external with quantities and cash; prices go in prices.
Receivables / payables. Type debt. Accrue with a positive debt for receivables (negative for payables), reverse on settlement. Keep the debt on the same code as the asset if you need instrument-level income.
Repo. Two legs, repo_l1 / repo_l2, linked by connected_transaction_id. Treat repo as cash plus interest, not as a security transfer: code_type = INSTRUMENT. securities is +1 / -1. Terms live on instruments. Reverse repo: first leg cash in, securities = 1.
Deposit. deposit with code_type = INSTRUMENT. Open: negative money, securities = 1. Close: opposite. Interest is interest.
FX. Two forex cash rows (code_type = CASH). TrackRecords infers the rate from the two money amounts.
Fees. Prefer a dedicated instrument in class “Manager remuneration”, then fee (and debt if you accrue first). fee_category distinguishes management, success, brokerage, and so on.
Dividends. Accrue debt from ex-date, then reverse debt and book dividend money on pay date so NAV includes the receivable before cash arrives.
prices
Prices under the client accounting policy, used to value the book on any date in the period.
Required when you send transactions and want TrackRecords to recalculate return. Dirty price currency should match the asset currency in the nearest holdings row.
Validation (selected rules)
| # | Check |
|---|---|
| 1 | Currencies are ISO 4217 |
| 2–4 | securities / money / debt required for the matching transaction_type |
| 5 | For trade, money and securities have opposite signs (unless a side is zero) |
| 9 | Cash rows use forex, transfer_internal, transfer_external, cash_interest or fee |
| 11 | Holdings value identity |
| 16–17 | Cash and security balances must not go negative |
| 21 | Payables: price_dirty and value ≤ 0 |
| 23–25 | Holdings at start + transactions = holdings at end (securities, money, debt) |
| 27 | nav matches portfolio NAV on the same date |
| 28 | Prices exist for non-cash, non-user-instrument codes |
| 34–35 | No duplicate transaction or price keys |
| 36 | Holdings price_dirty matches prices.price_dirty for the same code and date (debt classes excluded) |
A Windows validator (TR-Validator) can check a JSON or XLSX file offline. Ask support@trackrecords.app for the current build.
Load the same payload through the snapshot API or the transaction API.