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
page	integer	Page number (starts from 1, default: 1)
limit	integer	Results per page (1-100, default: 50)

Example Request

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

Response

{
  "companies": [
    {
      "company_id": 1,
      "symbol": "005930",
      "name": "Samsung Electronics",
      "alias_name": "삼성전자",
      "exchange": "KRX",
      "sector": "Technology",
      "country": "South Korea"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Pagination Response Fields

Field	Type	Description
page	integer	Current page number
limit	integer	Items per page
total	integer	Total number of items
total_pages	integer	Total number of pages
has_next	boolean	Whether next page exists
has_prev	boolean	Whether previous page exists

---

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

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

Response

{
  "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

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

{
  "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