Babylon Segment Ledger CSV Specification

A Babylon Segment is a record of all trades, or ledger, for a group of security positions, regardless of which brokerage account they were executed through. Any portfolio of trades can be partitioned into segments with each security, and all its trades, belonging to one and only one segment.

To put it another way, segments are a natural way to organise trades so that each security is recorded in one place only. No position in a security is ever split between segments.

This design supports accurate calculations of capital gains: it matters not which account a security was bought or sold through, all of its trades must be considered together in a single unit for calculation.

At the extremes, one could maintain one segment per security (the finest grouping) or a single global segment for all securities (the broadest grouping). Most setups fall somewhere in between—for example, a segment by bourse, country, or currency tends to arise naturally.

Required Columns:

• SegmentLedger: The name of the segment ledger, constant across all rows.

• AccountAlias: A user-friendly label for a brokerage account, used for reporting and organisation. It allows users to avoid exposing the actual broker account identifier, while still giving each account a clear and meaningful name.

  • Structure

    • Canonical form: <aliasName>-<accountType>
    • Shorthand: <aliasName> (if no <accountType> is given, it will be treated as -GIA during import)

  • Account types
    The account type suffix is mandatory in canonical form and must be in uppercase from the following list:

    • RA — Retirement Annuity (ZA)
    • TFSA — Tax-Free Savings Account (ZA)
    • ISA — Individual Savings Account (GB)
    • SIPP — Self-Invested Personal Pension (GB)
    • GIA — General Investment Account (default if omitted)

  • Examples
    The alias can be personalised (e.g., My-ISA, Bobs-SIPP) or simply reflect the platform name (e.g., AJBell, Saxo, IBKR) as one often has only one account of a specific type at any given brokerage.

    • Personalised: My-ISA, Bobs-SIPP
    • Platform-style: AJBell-ISA, AJBell-SIPP, Investec-GIA, IBKR-GIA, Saxo-GIA
    • Shorthand: MyAccount → imported as MyAccount-GIA

• Type: The transaction type. Use ‘Buy’ if a purchase and ‘Sell’ if a sale.

• Quantity: The number of shares or units traded, as a numerical value (e.g., 1000, 162.28, 2315.123). Decimals without thousand separators is preferred.

• Symbol: The listing ticker symbol (e.g., ‘FNBINF’, ‘PPE’, ‘CGT’, ‘PNL’). In the case of UK non-listed funds use the Sedol. In the case of South African non-listed funds use the assigned JSE alpha code.

• NetAmount: The total cost for buy transactions and the net proceeds for sell transactions. This quantity is distinct from the consideration as it includes all transaction costs.

• Currency: The currency of the NetAmount.

• SettleDate: The settlement date of the transaction, in YYYY-MM-DD format.

• Bourse: The code name of exchange where the security was traded. Use common codes such as LSE, JSE or MIC codes like XLON, XJSE. If the security is not a listed security but a unit trust or similar (e.g., “FUNDSMITH EQUITY FUND I CLASS INCOME”) then set the value to GBFUND or ZAFUND, or more generally <Country Code>FUND.

Optional Columns:

• Comments: Free form text for notes about the trade.

• ISIN: The ISIN number.

• TradeDate: The trade date of the transaction, in YYYY-MM-DD format.

• Commission: The commission charged by the broker. Assumed to be in the same currency as the NetAmount.

• Price: The price of one unit of the security.

The ‘Type’ field implies the sign of the fields ‘Quantity’ and ‘NetAmount’ are superfluous. We could specify that these fields are unsigned, but it is much more useful for spreadsheet work, if we clean up the signs. So we validate fields on upload (saving), and will correct and enforce signs consistent with the ‘Type’ field; that is, “Buy” => ‘Quantity’ is negative, “Sell” => “Quantity” is positive, and similarly for ‘NetAmount’.

The columns are not order sensitive.

An example GB ledger would be,

An example ZA ledger (with a slightly different column order) would be,

← Back to API