# Financials migration

> Move from legacy Stock Financials to annual or quarterly statements, or the latest combined TTM snapshot.

The legacy Stock Financials endpoint combined financial statements in one response. Choose the v2 resource according to the period and statement your application needs.

Annual and quarterly statements provide a series of reported periods. Financials TTM provides the most recent trailing-twelve-month snapshot across the three statements. A documentation migration does not update your existing API requests or parsers automatically.

<a id="choose-your-data"></a>

## Choose your data

- [Annual and quarterly statements](#annual-and-quarterly-statements): reported periods for income, balance sheet and cash flow
- [Latest TTM snapshot](#latest-ttm-snapshot): the latest combined bs, cf and ic blocks

| You need | Use | Response |
| --- | --- | --- |
| Annual or quarterly periods | Three dedicated statement endpoints; set `freq=annual` or `freq=quarterly` | `data.financials` on each endpoint |
| Latest TTM snapshot | [Financials TTM](https://docs.bavest.co/docs/v2_equities_financials_ttm.md); no `freq` parameter | `data.bs`, `data.cf`, `data.ic` |

<a id="annual-and-quarterly-statements"></a>

## Annual and quarterly statements

Request the statements you need separately. Set `freq` explicitly: it defaults to `annual`; use `quarterly` for quarterly periods. Provide exactly one of `symbol` or `isin` on every request.

- [Income Statements](https://docs.bavest.co/docs/v2_equities_income_statement.md): GET /v2/equities/income-statement
- [Balance Sheets](https://docs.bavest.co/docs/v2_equities_balance_sheets.md): GET /v2/equities/balance-sheets
- [Cash Flow Statements](https://docs.bavest.co/docs/v2_equities_cash_flow.md): GET /v2/equities/cash-flow

Read each response's `data.financials` array. Match rows by their reporting period, frequency and reported currency rather than joining the arrays by position. Preserve missing or null values when reconciling statements.

JSON response excerpt (OpenAPI example, not live data):

```json
{
  "data": {
    "currency": "USD",
    "financials": [
      {
        "date": "2025-09-27",
        "frequency": "annual",
        "reportedCurrency": "USD",
        "revenue": 416161000000,
        "netIncome": 112010000000
      }
    ]
  }
}
```

Annual statement requests:

```bash
curl 'https://api.bavest.co/v2/equities/income-statement?symbol=AAPL&freq=annual' \
  -H "x-api-key: $BAVEST_API_KEY"

curl 'https://api.bavest.co/v2/equities/balance-sheets?symbol=AAPL&freq=annual' \
  -H "x-api-key: $BAVEST_API_KEY"

curl 'https://api.bavest.co/v2/equities/cash-flow?symbol=AAPL&freq=annual' \
  -H "x-api-key: $BAVEST_API_KEY"
```

Quarterly income statement request:

```bash
curl 'https://api.bavest.co/v2/equities/income-statement?symbol=AAPL&freq=quarterly' \
  -H "x-api-key: $BAVEST_API_KEY"
```

The optional `fields` filter selects line-item response keys for that statement, such as `revenue` for income statements. This differs from the `metricId` filter on [Equity Metrics](https://docs.bavest.co/docs/v2_equities_metrics.md). Check each endpoint's field list before filtering.

<a id="latest-ttm-snapshot"></a>

## Latest TTM snapshot

Use GET /v2/equities/financials-ttm for the most recent combined snapshot. Provide exactly one of symbol or isin. This endpoint has no freq parameter and does not return a full annual or quarterly history.

- [Open Financials TTM](https://docs.bavest.co/docs/v2_equities_financials_ttm.md): parameters, full JSON example and response fields

The result contains `data.bs` for balance sheet, `data.cf` for cash flow and `data.ic` for income statement. The current example supplies the snapshot date as `data.date` and currency as `data.currency`. Read those values; if individual blocks also provide period metadata, preserve it when reconciling statements.

JSON response excerpt (OpenAPI example, not live data):

```json
{
  "data": {
    "date": "2026-06-27",
    "currency": "USD",
    "bs": {
      "totalAssets": 373221500000
    },
    "cf": {
      "freeCashFlow": 136683000000
    },
    "ic": {
      "revenue": 466823000000,
      "netIncome": 128930000000
    }
  }
}
```

Latest TTM request:

```bash
curl 'https://api.bavest.co/v2/equities/financials-ttm?symbol=AAPL' \
  -H "x-api-key: $BAVEST_API_KEY"
```

Use `fields` to select statement line items. A field is retained only in the `bs`, `cf` or `ic` block that reports it; unsupported names can leave blocks empty. Use the dedicated statement endpoints when you need annual or quarterly periods.

<a id="migration-checklist"></a>

## Migration checklist

1. Choose reported annual/quarterly periods or the latest TTM snapshot before changing the API call.
2. Replace the legacy POST request with the documented GET request and query parameters. Send your API key in the `x-api-key` header; the examples read `BAVEST_API_KEY` from the environment.
3. Update parsing to `data.financials` or the `data.bs` / `data.cf` / `data.ic` blocks. Do not assume the legacy response shape is unchanged.
4. Compare period ends, frequencies, currencies and the specific fields your application uses before replacing calculations. A latest TTM snapshot is not a substitute for every historical reporting period.

- [Authentication guide](https://docs.bavest.co/docs/authentication.md)
- [Equity Metrics migration](https://docs.bavest.co/docs/v2_equities_metrics.md#migration)
- [All API routes](https://docs.bavest.co/docs.md)

---

HTML version: https://docs.bavest.co/docs/financials-migration. Docs index for agents: https://docs.bavest.co/llms.txt. OpenAPI: https://docs.bavest.co/openapi.json.
