> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/en/api-reference/public-api/financial.md).

# Financial

Access company information and financial statement data.

**Required Scope:** `read:financial` or `read:all`

## List Companies

Get a list of companies with optional filtering.

```
GET /api/public/v1/financial/companies
```

### Query Parameters

| Parameter | Type    | Description                           |
| --------- | ------- | ------------------------------------- |
| `search`  | string  | Search by name or symbol              |
| `sector`  | string  | Filter by sector                      |
| `country` | string  | Filter by country                     |
| `limit`   | integer | Results per page (1-100, default: 50) |
| `offset`  | integer | Pagination offset (default: 0)        |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies?search=samsung&limit=10" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "companies": [
    {
      "company_id": 1,
      "symbol": "005930",
      "name": "Samsung Electronics",
      "alias_name": "삼성전자",
      "exchange": "KRX",
      "sector": "Technology",
      "country": "KR"
    }
  ],
  "total": 1
}
```

***

## Get Company by Symbol

Get company information by stock symbol.

```
GET /api/public/v1/financial/companies/{symbol}
```

### Path Parameters

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `symbol`  | string | Stock symbol (e.g., "005930") |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "company_id": 1,
  "symbol": "005930",
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "exchange": "KRX",
  "sector": "Technology",
  "country": "KR"
}
```

***

## Get Company Financials

Get financial statements time series data for a company.

```
GET /api/public/v1/financial/companies/{symbol}/financials
```

### Path Parameters

| Parameter | Type   | Description  |
| --------- | ------ | ------------ |
| `symbol`  | string | Stock symbol |

### Query Parameters

| Parameter | Type    | Description                                    |
| --------- | ------- | ---------------------------------------------- |
| `period`  | string  | "Annual" or "Quarterly" (default: "Annual")    |
| `years`   | integer | Number of years to retrieve (1-20, default: 5) |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930/financials?period=Annual&years=5" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "statements": [
    {
      "fiscal_date": "2023-12-31",
      "year": 2023,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "gross_profit": 85000000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "total_liabilities": 120000000000000,
      "total_shareholders_equity": 335000000000000,
      "operating_cash_flow": 50000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}
```

### Financial Statement Fields

**Income Statement:**

* `sales`, `cost_of_goods`, `gross_profit`
* `operating_income`, `net_income`
* `ebit`, `ebitda`
* `eps_basic`, `eps_diluted`

**Balance Sheet:**

* `total_assets`, `total_current_assets`, `total_non_current_assets`
* `total_liabilities`, `total_current_liabilities`, `total_non_current_liabilities`
* `total_shareholders_equity`
* `cash`, `inventory`, `accounts_receivable`

**Cash Flow:**

* `operating_cash_flow`, `investing_cash_flow`, `financing_cash_flow`
* `free_cash_flow`, `capital_expenditures`