Read a submission as facts: completeness per metric, the metric by year matrix with loss ratios, one cell with its basis, and filtered facts with source cells.
Four read routes answer questions about one submission under one target structure. Every route takes the workbook documentId in the path and spec_id as a query parameter, and returns 404 when the target structure is not the workspace's. Completeness shows which metrics the submission covers, the matrix shows the figure per metric and year, a cell explains one figure, and facts returns the underlying rows.
A figure is never a blind sum. Totals win over their parts, only the latest valuation of a cumulative figure counts, and rates and ratios are never summed. When the rows of a cell disagree, for example because two tables report the same metric differently, the cell has basis: mixed and a null value, and alternatives holds one sum per workbook column. The basis values are single, total, sum and mixed.
GET/v1/submissions/{documentId}/completeness
Parameters
documentId*uuidThe workbook document.
spec_id*uuidThe target structure.
Response fields (data.metrics[])
metricstringThe metric name.
in_formatbooleanTrue when the target structure knows the metric. Metrics the submission has facts for but the structure does not know follow with false.
factsintegerFacts of the metric.
fieldsstring[]Fields the facts of the metric fill.
GET/v1/submissions/{documentId}/matrix
Response fields (data)
yearsstring[]Years found, ascending.
rows[].metricstringThe metric.
rows[].familystringpremium, losses, exposure, cat, rates, other or ratio.
rows[].yearsobjectFacts per year. The key "" collects facts with no period.
rows[].valuesobjectThe figure each year stands for: { value, basis } by year. value is null when the cell has no single figure.
rows[].failedstring[]Years with a failed check on one of their facts.
rows[].formulastringFor derived rows such as the loss ratio: how they are computed.
A derived Loss ratio row comes first in the matrix when incurred and earned premium both have a figure for a year. Its formula says how it was computed, so the ratio is never a number without a derivation.
Cell figures apply a table's stated unit such as "(000s)" only when every column of the table looks like that unit. The facts route and the export keep the workbook's own numbers, so a figure in cell can differ from the same figure in facts by that unit factor.
Frequently asked questions
Why is the value of a cell null?+−
The rows of the cell come from tables that disagree, so no single figure exists. The cell then has basis mixed and a null value, and alternatives holds one sum per workbook column with the column with most rows first. Pick the column that matches the client's definition.
How is the loss ratio computed?+−
The matrix adds a derived Loss ratio row when incurred and earned premium both have a figure for a year. The row carries a formula field that names the computation. Rates and ratios from the workbook itself are never summed.
What does an empty year key mean?+−
The empty key collects facts that have no period. In the matrix it is the key "" of a row's years object; in the cell and facts routes an empty year parameter selects the same facts.