API

Welcome to the Babylon API documentation.

The API provides programmatic access to five core areas:

Holdings — saved segment ledgers, cash ladders, bond ladders and savings sets.
Reference — current and historic security listings and corporate-action splits.
Compute — positions, capital gains and cash-flow calculations applied to segment ledgers and ladders.
Extract — extraction of segment entries from CSV, Excel, PDF, email and natural-language sources.
System — service availability information.

Many endpoints return a tabular JSON object with table metadata, a list of columns and row objects. Plain table responses can also be requested as CSV where the endpoint states that this is supported.

Global rules

All requests require Authorization: Bearer <api_key>; authentication is omitted from the examples.
GET requests supply operation parameters in the query string.
POST requests supply operation parameters in a JSON request body unless an endpoint states otherwise.
Responses are JSON by default.
For endpoints that return a plain table, request CSV with Accept: text/csv. The file-extraction endpoint also accepts "format": "csv" in its JSON body.
Tabular JSON uses the envelope name, description, columns, columnTypes and rows. Row field names are camel case. Decimal values are encoded as strings and identified in columnTypes.
Parameter names and output fields are endpoint-specific. format and columns are not universal parameters.

The two tabular source formats have their own detailed specifications:

The API is continually evolving, and this documentation will grow as endpoints and features are added.

Endpoints

Holdings

/holdings/bond-ladders — List Babylon bond-ladder identifiers and read a saved bond ladder.
/holdings/ladders — List Babylon cash-ladder identifiers and read a saved cash ladder.
/holdings/savings-sets — List Babylon savings-set identifiers and read a saved savings set.
/holdings/segments — List Babylon segment identifiers and read a saved segment ledger.

Reference

/reference/listings — List reference information for securities used by a segment ledger or bond ladder.
/reference/listings-historic — List historic security-reference records used by a segment ledger or bond ladder.
/reference/splits — List security splits relevant to a segment ledger.

Compute

/compute/bond-ladder-flows — Compute projected coupon and principal flows for a bond ladder.
/compute/capital-gains — Compute realised capital gains for a tax year over a Babylon segment ledger.
/compute/capital-gains-uk — Compute UK capital gains for a segment ledger under HMRC rules.
/compute/capital-gains-za — Compute South African capital gains for a segment ledger under SARS rules.
/compute/cash-ladder-flows — Compute projected cash flows and a monthly report for a cash ladder.
/compute/cash-ladder-historic-flows — Compute the complete historic and projected flow schedule for a cash ladder.
/compute/cash-ladder-taxable-flows — Compute taxable interest flows for a cash ladder and tax year.
/compute/ladder-flows — Compute projected cash flows for one or more cash and bond ladders.
/compute/position — Compute current security positions across a Babylon segment, including quantities, cost basis and unit costs.

Extract

/extract/segments/from-file — Extract one or more segment entries from a CSV, TSV, Excel, PDF or email file.
/extract/segments/from-quick-entry — Extract a segment entry from a natural-language sentence.

System

/system/status — Check whether the Babylon API service is available.