> 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/company/page-5.md).

# Company Tabs API

The company detail page uses a tab-based layout with 7 tabs, each powered by dedicated API endpoints.

## Tab Overview

| Tab        | ID           | Primary Endpoint                          | Description                                |
| ---------- | ------------ | ----------------------------------------- | ------------------------------------------ |
| Overview   | `overview`   | `/companies/{id}`                         | Company profile, stats, and summary cards  |
| Financials | `financials` | `/companies/{id}/financials`              | Income statement, balance sheet, cash flow |
| Chart      | `chart`      | TradingView widget                        | Interactive price chart                    |
| Disclosure | `disclosure` | `/companies/{id}/dart`                    | Korean corporate filings (DART)            |
| Insider    | `insider`    | `/companies/{id}/insider`                 | Insider trading data                       |
| Analysis   | `analysis`   | `/companies/{id}/snapshot` + `/technical` | Technical signals and AI analysis          |
| Consensus  | `consensus`  | `/companies/{id}/consensus`               | Expert forecasts and target prices         |

***

## Company Detail

Returns full company profile including financial metrics, valuation, growth, and health indicators.

```
GET /v1/financial_v4/companies/{company_id}
```

### Path Parameters

| Parameter    | Type    | Description |
| ------------ | ------- | ----------- |
| `company_id` | integer | Company ID  |

### Response

```json
{
  "id": 1,
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "symbol": "005930",
  "exchange": "KRX",
  "currency": "KRW",
  "current_price": 58000,
  "price_change": 1200,
  "price_change_percent": 2.11,
  "description": "Samsung Electronics Co., Ltd. ...",
  "ceo": "Jong-Hee Han",
  "website": "https://www.samsung.com",
  "sector": "Technology",
  "industry": "Semiconductors",
  "employees": 267800,
  "fiscal_year": 2024,
  "fiscal_date": "2024-12-31",
  "profile": {
    "market_cap": 346000000000000,
    "revenue": 258935000000000,
    "shares_outstanding": 5969783000,
    "employees": 267800
  },
  "margins": {
    "gross_margin": 32.8,
    "ebitda_margin": 18.5,
    "operating_margin": 2.54,
    "pretax_margin": 3.12,
    "net_margin": 5.98
  },
  "valuation": {
    "pe_ratio": 37.4,
    "pb_ratio": 1.03,
    "ps_ratio": 1.34,
    "ev_ebitda": 7.22,
    "pfcf_ratio": 11.5
  },
  "growth": {
    "sales_growth_3y_cagr": -2.1,
    "sales_growth_5y_cagr": 3.8,
    "operating_income_growth_3y_cagr": -15.2,
    "operating_income_growth_5y_cagr": -8.4,
    "net_income_growth_3y_cagr": -10.5,
    "net_income_growth_5y_cagr": -5.1
  },
  "returns": {
    "roa": 3.4,
    "roe": 4.6,
    "roic": 3.9
  },
  "financial_health": {
    "cash": 65000000000000,
    "net_debt": -20000000000000,
    "debt_to_equity_ratio": 0.36,
    "interest_coverage_ratio": 8.5
  }
}
```

**Used by:** Overview tab — company header, stats grid, financial metrics cards

***

## Resolve Company Slug

Convert a URL slug or ticker symbol to a company ID. Used for routing.

```
GET /v1/financial_v4/companies/by-slug/{slug}
```

### Path Parameters

| Parameter | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| `slug`    | string | Company slug or ticker (e.g., `samsung-electronics`, `005930`) |

### Response

```json
{
  "id": 1,
  "name": "Samsung Electronics",
  "symbol": "005930",
  "exchange": "KRX"
}
```

***

## Company Financials

Returns time-series financial statements (income statement, balance sheet, cash flow).

```
GET /v1/financial_v4/companies/{company_id}/financials
```

### Query Parameters

| Parameter | Type    | Default    | Description                 |
| --------- | ------- | ---------- | --------------------------- |
| `period`  | string  | `"Annual"` | `"Annual"` or `"Quarterly"` |
| `years`   | integer | `5`        | Number of years to retrieve |

### Response

```json
{
  "statements": [
    {
      "fiscal_date": "2024-12-31",
      "year": 2024,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}
```

**Full field list:** See [Financial Statement Fields](#financial-statement-fields) below.

**Used by:** Financials tab — sub-tabs for Income Statement, Balance Sheet, Cash Flow with annual/quarterly toggle

***

## Company Snapshot

Returns real-time market data from yfinance including analyst recommendations.

```
GET /v1/financial_v4/companies/{company_id}/snapshot
```

**Used by:** Analysis tab — key metrics display, AI signal banner

***

## Company Technical

Returns technical indicators calculated from price data.

```
GET /v1/financial_v4/companies/{company_id}/technical
```

### Response includes

* **RSI** (Relative Strength Index)
* **MACD** (Moving Average Convergence Divergence)
* **Bollinger Bands** (upper, middle, lower)
* **ATR** (Average True Range)
* **SMA** (Simple Moving Averages — 20, 50, 200 day)

**Used by:** Analysis tab — technical signals component

***

## Company News

Returns news articles from Perigon API and Google News RSS.

```
GET /v1/financial_v4/companies/{company_id}/news
```

### Query Parameters

| Parameter | Type    | Default | Description                      |
| --------- | ------- | ------- | -------------------------------- |
| `limit`   | integer | `3`     | Number of articles to return     |
| `locale`  | string  | `"ko"`  | Language locale (`"ko"`, `"en"`) |

**Used by:** Overview tab — news card (lazy-loaded below the fold)

***

## Company DART Disclosures

Returns Korean corporate disclosure filings from the DART system.

```
GET /v1/financial_v4/companies/{company_id}/dart
```

### Query Parameters

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `limit`   | integer | `3`     | Number of filings to return |

**Used by:** Disclosure tab, Overview tab — DART card

***

## Company Research Highlights

Returns analyst research report summaries.

```
GET /v1/financial_v4/companies/{company_id}/research-highlights
```

### Query Parameters

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `limit`   | integer | `3`     | Number of reports to return |

**Used by:** Overview tab — research highlights card

***

## Company Sector Analysis

Returns sector-level analysis for the company.

```
GET /v1/sector-analyst/company/{company_id}
```

### Query Parameters

| Parameter | Type   | Default | Description     |
| --------- | ------ | ------- | --------------- |
| `locale`  | string | —       | Language locale |

**Used by:** Overview tab — sector analysis card (lazy-loaded)

***

## Company Consensus

Returns expert forecast consensus including target prices and investment opinions.

```
GET /v1/financial_v4/companies/{company_id}/consensus
```

### Query Parameters

| Parameter | Type    | Default | Description               |
| --------- | ------- | ------- | ------------------------- |
| `months`  | integer | `12`    | Analysis period in months |

### Response

```json
{
  "company_id": 1,
  "company_name": "Samsung Electronics",
  "symbol": "005930",
  "currency": "KRW",
  "has_consensus": true,
  "message": null,
  "current_price": 58000,
  "target_prices": {
    "average": 85000,
    "high": 110000,
    "high_broker": "미래에셋증권",
    "low": 65000,
    "low_broker": "대신증권",
    "std_dev": 12500,
    "expert_count": 25
  },
  "upside_downside": {
    "current_price": 58000,
    "to_high": 89.66,
    "to_average": 46.55,
    "to_low": 12.07
  },
  "investment_opinions": [
    { "opinion": "매수", "count": 18, "percentage": 72.0 },
    { "opinion": "중립", "count": 5, "percentage": 20.0 },
    { "opinion": "매도", "count": 2, "percentage": 8.0 }
  ],
  "target_price_trend": [
    {
      "date": "2024-03-15",
      "target_price": 90000,
      "broker": "삼성증권",
      "opinion": "매수"
    }
  ],
  "price_history": [
    { "date": "2024-01-02", "close": 52000 }
  ],
  "analysis_period_months": 12,
  "last_report_date": "2024-03-20",
  "total_reports": 42
}
```

**Used by:** Consensus tab — target price chart, opinion distribution, broker detail table

***

## Company Insider

Returns insider trading data for the company.

```
GET /v1/financial_v4/companies/{company_id}/insider
```

**Used by:** Insider tab, Disclosure tab — insider trading embed

***

## Financial Statement Fields

The financials endpoint returns these fields for each statement period:

### Income Statement (손익계산서)

| Field                                | Description               |
| ------------------------------------ | ------------------------- |
| `sales`                              | Revenue (매출액)             |
| `cost_of_goods`                      | Cost of goods sold (매출원가) |
| `gross_profit`                       | Gross profit (매출총이익)      |
| `research_and_development`           | R\&D expenses (연구개발비)     |
| `selling_general_and_administrative` | SG\&A expenses (판매관리비)    |
| `operating_income`                   | Operating income (영업이익)   |
| `ebit`                               | EBIT                      |
| `ebitda`                             | EBITDA                    |
| `pretax_income`                      | Pretax income (세전이익)      |
| `net_income`                         | Net income (당기순이익)        |
| `eps_basic`                          | Basic EPS (기본주당순이익)       |
| `eps_diluted`                        | Diluted EPS (희석주당순이익)     |

### Balance Sheet (재무상태표)

| Field                           | Description                        |
| ------------------------------- | ---------------------------------- |
| `total_assets`                  | Total assets (자산총계)                |
| `total_current_assets`          | Current assets (유동자산)              |
| `cash_and_cash_equivalents`     | Cash & equivalents (현금및현금성자산)      |
| `accounts_receivable`           | Accounts receivable (매출채권)         |
| `inventory`                     | Inventory (재고자산)                   |
| `total_non_current_assets`      | Non-current assets (비유동자산)         |
| `properties`                    | Property, plant & equipment (유형자산) |
| `intangible_assets`             | Intangible assets (무형자산)           |
| `goodwill`                      | Goodwill (영업권)                     |
| `total_liabilities`             | Total liabilities (부채총계)           |
| `total_current_liabilities`     | Current liabilities (유동부채)         |
| `total_non_current_liabilities` | Non-current liabilities (비유동부채)    |
| `total_shareholders_equity`     | Total equity (자본총계)                |
| `retained_earnings`             | Retained earnings (이익잉여금)          |

### Cash Flow (현금흐름표)

| Field                  | Description                    |
| ---------------------- | ------------------------------ |
| `operating_cash_flow`  | Operating cash flow (영업활동현금흐름) |
| `investing_cash_flow`  | Investing cash flow (투자활동현금흐름) |
| `financing_cash_flow`  | Financing cash flow (재무활동현금흐름) |
| `capital_expenditures` | CapEx (유형자산취득)                 |
| `free_cash_flow`       | Free cash flow (잉여현금흐름)        |
| `common_dividends`     | Dividends paid (배당금지급)         |

***

## Frontend Hooks Reference

Each API endpoint is wrapped in a React Query hook with optimized caching:

| Hook                     | Endpoint                              | Stale Time | Cache Time |
| ------------------------ | ------------------------------------- | ---------- | ---------- |
| `useCompanyDetail()`     | `/companies/{id}`                     | 5 min      | 10 min     |
| `useCompanyFinancials()` | `/companies/{id}/financials`          | 1 hour     | 2 hours    |
| `useCompanySnapshot()`   | `/companies/{id}/snapshot`            | 1 min      | —          |
| `useCompanyTechnical()`  | `/companies/{id}/technical`           | —          | —          |
| `useCompanyNews()`       | `/companies/{id}/news`                | 1 min      | —          |
| `useCompanyDart()`       | `/companies/{id}/dart`                | 1 min      | —          |
| `useCompanyResearch()`   | `/companies/{id}/research-highlights` | 1 min      | —          |
| `useStockAnalysis()`     | Stock analysis service                | 5 min      | 10 min     |

### Tab Navigation

Tabs use URL hash routing (`#overview`, `#financials`, etc.) with lazy-loaded components via Next.js `dynamic()` imports. Each tab component only fetches data when activated.

```typescript
type TabId = "overview" | "financials" | "chart" | "disclosure" 
           | "insider" | "analysis" | "consensus";
```