Data conventions

Units

meta.unit_note and similar descriptive strings are in Korean. 억원 (eok won) means KRW 100 million; 백만달러 means USD millions.

Currency

• Korean stocks are in won (KRW) and US stocks in dollars (USD). We do not convert between them.
• Values that can mix currencies, such as dividends, come with a currency field.
• When currencies or bases differ, the PRO API variance table (/earnings/{symbol}/variance) does not compute a difference (%) and gives the reason in reasons.

Fiscal and calendar periods

• Financial values follow the company's fiscal period. Most Korean listed companies close their books in December, but a US company's fiscal year can differ from the calendar year (for example, a fiscal year ending in September). Read fiscal_year and period together.
• PRO API period parameters look like FY2027Q2, 2026 3분기 (Q3 2026) or 2026 (full year).
• Korean Q2–Q4 values may be derived by subtracting the previous cumulative figure from a cumulative report. In that case derived_from names the subtracted report. Values from preliminary earnings filings have preliminary: true.
• fs distinguishes consolidated from separate statements. Korean EPS, PER and ROE are based on net income attributable to controlling shareholders, marked by eps_basis (controlling · total).

Dates and times

• Timestamps (as_of, published_at, etc.) are ISO 8601 strings in UTC (ending in Z). Add 9 hours for KST.
• Read date-only values (YYYY-MM-DD) as is, without time-zone conversion. Korean data uses Korean dates; US filing and earnings schedules use US local dates. Turning a date string into midnight and then applying a time zone can shift it by a day.
• Dates for the daily quota and usage (X-Quota-Period, usage.day) are in KST.
• PRO API quotes tell you which session a value comes from with session and regular.label (정규장 현재가, regular-session price · 정규장 종가, regular-session close). Pre-market, after-hours and day-market trades are kept separately in extended.

Sources and as-of time

Every PRO API data response uses the same envelope.

{
  "data": { "...": "endpoint-specific values" },
  "as_of": "2026-10-21T06:35:10.000Z",
  "sources": [
    { "name": "DART", "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261021000123" }
  ],
  "disclaimer": "…",
  "meta": { "unit_note": "국내 억원 · 미국 백만달러" }
}

• as_of: the point in time the values refer to. It can differ from when the response was generated (for example, the quote date).
• sources: a list of source links. It contains only DART and SEC originals and Phoenix AI page links.
• Financial rows carry report (report name), rcept_date (filing date) and source_url (link to the original).
• AI filing summaries use source to say whether the summary is stored (cache) or was generated for this request (generated).
• Data API filing responses include the receipt number and a link to the original; news includes the publisher name (publisher) and a link to open the original article.

Data coverage (markets)

• Data is provided per contract for Korea (KR), the United States (US) or both. Japan (JP) and China (CN) data are coming soon.
• Your account’s markets are in markets on GET /key (with markets_available and markets_coming_soon), the X-Markets response header and the coverage card in the developer console.
• The market comes from the symbol (6-digit Korean code = KR, US ticker = US) or the market parameter. A market outside your contract returns 403 MARKET_NOT_ENTITLED; Japan and China return 400 MARKET_NOT_AVAILABLE.
• On lists that take market, leaving it out picks your market when the account has only one. The mixed-market news feed returns articles from your markets only.

Data API response envelope

• Single document: { data, meta }. List: { data, next_cursor, has_more, meta }. For the next page, send next_cursor unchanged with the same filters.
• meta always carries as_of (response time); company endpoints (/companies/{symbol}/…) also carry disclaimer, unit_note and page_url.
• Errors are always { error: { code, message, docs } }. This differs from the PRO API frame above (with sources); don't mix them up.

Units and currency by endpoint

Machine-readable codes

• period_code: fiscal year FY2025 · quarter 2026Q3 · year-to-date 2025YTDQ2 (first half) / 2025YTDQ3 (Q1–Q3). Company fiscal calendar (for US companies check the actual dates in period_end).
• account_code: the account codes below. fs_code: CFS (consolidated) / OFS (separate). unit_code: KRW_EOK, USD_MIL, USD, KRW, SHARES_MIL.
• report_code: Korea annual_report, half_year_report, q1_report, q3_report; US SEC forms (10-K, 10-Q, 20-F, 8-K …).
• Korean fields (account, period, report, name) are display strings. Sort, join and filter on the code fields.

Account codes

The account parameter and the account_code field of /companies/{symbol}/financials. An English code matches exactly that account; a Korean name matches by substring (e.g. 순이익 → both net-income lines). Pass several separated by commas; an unknown English word returns 400 BAD_REQUEST.

Period input (period)

• Financial statements: fiscal year FY2025 or 2025; quarter 2026Q2, FY2026 Q2 or Q2 2026; Korea-only year-to-date 2025H1 (= 2025YTDQ2) or 2025YTDQ3; plus latest_quarter, annual, quarterly. Korean forms (2025 연간, 2026 2분기, 2025 반기 누적) are accepted too.
• Consensus and guidance: 2026Q3 or FY2027Q2 (quarter), FY2026 or 2026 (year), last / next (previous / next quarter).
• Anything else returns 400 BAD_PERIOD. A period_code from a response can be passed back as-is.

Samsung Electronics · 005930

curl -sG "https://api.chickstockfi.com/openapi/v1/companies/005930/financials" \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  --data-urlencode "account=revenue,operating_income" \
  --data-urlencode "period=2026Q2" \
  --data-urlencode "fs=CFS"

Financial statements: order and pages

• Order: fiscal year and quarter, newest first (within a year: annual, then Q4 down to Q1; year-to-date rows after the same quarter) → account (statement order) → consolidated (CFS) first → filing ledger first.
• Pages: limit (default 100, max 200) + cursor. Without account and period you get the whole ledger from the latest period; follow next_cursor for the rest (meta.total = total rows). Rows are in data.rows.
• fs=CFS or fs=OFS selects consolidated or separate statements (Korea). US rows are CFS.

Periods filled from company IR materials

• Filed values (DART, SEC) come first. Only (account, period) pairs missing from the ledger are filled from company IR materials, with source = 기업 IR 자료 (company IR materials).
• Only revenue, operating income, net income, total liabilities, total equity, current assets and current liabilities are filled, so a filled period carries only some accounts. meta.partner_filled_periods and partner_filled_accounts list them.
• IR rows are not filings, so report, report_code, filed_date, source_url and period_end are null.

Consensus and guidance

• Consensus covers revenue and operating income in Korea, revenue only in the US. meta.metrics lists what is actually served for the market.
• For reported periods, vs_consensus_pct is calculated only when a consensus observed before the announcement date (reported_on) exists (consensus_at_report). Otherwise it is null and comparison_status says why — compared · basis_unconfirmed · no_pre_report_estimate (no pre-report value, or announcement date unknown) · no_actual · upcoming.
• For some US periods the source gives no announcement time, so reported_on is null and no pre-report value is picked.
• In guidance (/companies/{symbol}/guidance), value, low and high are raw KRW / USD and unit / unit_scale (1) describe them. The table unit is display_unit / display_scale (value ÷ display_scale = number in display_unit).

Filtering filings (US)

• On /companies/{symbol}/disclosures, filter US companies with form=10-K,10-Q,8-K (only these; 10-K includes 10-K/A) or exclude_forms=424B2,SC 13G (all but these), up to 10 forms.
• Without a filter, high-volume repetitive forms (424B2, SC 13G …) are limited to part of the list. Passing these filters for a Korean company returns 400 BAD_REQUEST.
• Every filing row carries report_code (Korean periodic-report code or SEC form).

News coverage

• market=KR is Korean-language articles from Korean media; market=US is US articles (English-language articles from international media, company press releases, SEC filing alerts). Omit it for both. Only articles Phoenix AI has already collected are returned.
• For US English articles title is the original and title_ko the Phoenix AI Korean translation (or null). lang is the language of title.
• publisher is the publisher name. When an aggregator's name appears in that place it is shown as 해외 언론 (overseas media) or 뉴스 (news).
• The symbol filter returns only articles with a verified symbol tag, so a page can be shorter than limit — follow has_more and next_cursor. Re-sent copies of the same story (near-duplicates) are reduced to one per page.

Quotes (/quotes)

• data.valuation is the same calculation as valuation in /companies/{symbol}/metrics (basis, eps_basis — Korean EPS and P/E use net income attributable to owners). Not-applicable values that arrived as 0 are null.
• Top-level fields (symbol, price, fundamentals …) are kept for legacy clients (deprecated) with their old values and units (fundamentals.debt_ratio is a ratio: 0.311 = 31.1%). New code should read data.

Data API · Errors

Empty values and symbols

• When a value cannot be determined, it is null. Do not confuse it with 0.
• Korean stocks use 6-digit codes (for example Samsung Electronics · 005930); US stocks use tickers (for example Apple · AAPL). The reference lists the supported markets for each endpoint.