# Retrieve a financial statement

Operation ID: `runFinancialStatement`

Group: Accounting › Reports › Financial Statement

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/runFinancialStatement)

`POST /accounting/reports/financial-statement`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Retrieves a financial statement. You send one legal entity, one accounting book and the accounting periods in periodIds. When consolidated is true, the report also covers every legal entity beneath that entity.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Request body

Required, `application/json`: runFinancialStatementInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `statementId` | string | yes | The configured statement template to run. A template that has been deleted is reported as STATEMENT_NOT_FOUND. This API has no endpoint that lists the templates. |
| `entityId` | string | yes | The entity to report on. When consolidated is false, this is the reporting entity on its own. When true, this is the consolidating parent and the report covers its whole hierarchy. Exactly one entity per request. See id on GET base/entities. |
| `bookId` | string | yes | The accounting book to report from. It must belong to entityId. A book that belongs to another entity is reported as BOOK_NOT_FOUND. Exactly one book per request, because amounts from different books are not comparable. See id on GET accounting/books/:id. |
| `periodIds` | array<string> | yes | The accounting periods to report over, at least one. Period names are not accepted, because their format varies per fiscal calendar. The periods need not be contiguous, and how they become columns depends on the template and on splitBy. See id on GET accounting/accounting-periods/:id. |
| `consolidated` | boolean | no | Whether to report the consolidated statement for entityId and every entity beneath it, with amounts translated into the parent's currency. When false, only this entity is reported, with no translation. Defaults to false. |
| `splitBy` | any | no | Adds a further column split to the report, beyond the periods it reports over. Omit for the plain statement with no split. The time splits 'month', 'quarter' and 'year' subdivide the requested periods. The dimension splits break each figure out by that dimension, such as entity, department, business unit, vendor or customer. 'entity' is meaningful only when consolidated is true. 'aggregatedDepartment' rolls the department hierarchy up to its top level, where 'department' keeps each department on its own. One of: `"month"`, `"quarter"`, `"year"`, `"entity"`, `"department"`, `"aggregatedDepartment"`, `"businessUnit"`, `"vendor"`, `"customer"`. |

```json
{
  "statementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "bookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "periodIds": [
    "<periodIds>"
  ],
  "consolidated": true,
  "splitBy": "month"
}
```

## Response

`200` Success

Under `data` (runFinancialStatementOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `statementId` | string | yes | The statement template that produced this report, echoing the statementId input. |
| `statementName` | string | yes | The template's configured name. |
| `statementType` | string | yes | The reporting standard and statement kind of the template that ran. Possible values: 'generic', 'coaIncomeStatement', 'coaBalanceSheet', 'gaapIncomeStatement', 'gaapBalanceSheet', 'cashFlow', 'hgbIncomeStatement', 'hgbBalanceSheet', 'ifrsStatementOfProfitOrLoss', 'ifrsStatementOfFinancialPosition', 'ifrsStatementOfOtherComprehensiveIncome', 'sfrsStatementOfProfitOrLoss', 'sfrsStatementOfFinancialPosition', 'sfrsStatementOfOtherComprehensiveIncome'. |
| `data` | UnknownValue | yes | The computed report, produced by the statement calculation. It has no fixed schema: the shape depends on the template's type and on splitBy. Expect a hierarchy of statement lines with their computed amounts per column, and account-level detail rows are always present, so you can aggregate or drill down. Treat unfamiliar fields as data rather than an error. |

```json
{
  "data": {
    "statementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "statementName": "<statementName>",
    "statementType": "<statementType>",
    "data": "<data>"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Errors

| Code | Status |
| --- | --- |
| `STATEMENT_NOT_FOUND` | 400 |
| `ENTITY_NOT_FOUND` | 400 |
| `BOOK_NOT_FOUND` | 400 |
| `PERIOD_NOT_FOUND` | 400 |
| `PERIODS_REQUIRED` | 400 |
| `ENTITY_SPLIT_REQUIRES_CONSOLIDATION` | 400 |
| `MALFORMED_ID` | 400 |
| `STATEMENT_CALCULATION_FAILED` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: STATEMENT_NOT_FOUND, ENTITY_NOT_FOUND, BOOK_NOT_FOUND, PERIOD_NOT_FOUND, PERIODS_REQUIRED, ENTITY_SPLIT_REQUIRES_CONSOLIDATION, MALFORMED_ID, STATEMENT_CALCULATION_FAILED
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error