Query financial statements

Select issuers, reporting scopes, periods, metrics, ratios, currency, metadata, and filing sources without downloading an entire company history.

Use GET /v1/financials/statements for ticker-based queries or GET /v1/companies/{company_id}/statement-financials when you already have a Rangler company ID.

Select an issuer

GET /v1/financials/statements?ticker=ACCESSCORP&country_code=NG

Ticker matching is case-insensitive. country_code disambiguates tickers reused in more than one supported market. The response's company object contains the resolved ID, name, ticker, exchange, and market code—clients do not need to reconstruct company identity from the request.

Project only what you need

curl -sG "https://api.rangler.co/v1/financials/statements" \
  -H "X-API-Key: rgl_live_your_key_here" \
  --data-urlencode "ticker=ACCESSCORP" \
  --data-urlencode "country_code=NG" \
  --data-urlencode "statement_type=income_statement,cash_flow" \
  --data-urlencode "metric=revenue,profit_after_tax,operating_cash_flow" \
  --data-urlencode "ratio=pat_margin,return_on_equity" \
  --data-urlencode "period_family=annual" \
  --data-urlencode "latest_only=true" \
  --data-urlencode "include_sources=false"

List selectors accept either repeated parameters or comma-separated values:

?metric=revenue&metric=profit_after_tax
?metric=revenue,profit_after_tax

Unknown selector keys return a validation error rather than being silently ignored.

Query parameters

Parameter	Values	Behavior
`ticker`	exchange ticker	Required on the ticker route.
`country_code`	ISO alpha-2 code	Disambiguates a ticker across markets.
`scope`	`auto`, `consolidated`, `separate`, `unspecified`	`auto` selects the best filing-backed reporting scope.
`scope_label`	a returned subject label	Selects a parallel subject such as `Bank` when the filing reports more than one.
`granularity`	`all`, `annual`, `quarterly`	Broad period selection retained for compatibility.
`period_family`	`annual`, `quarterly`, `semi_annual`, `nine_month`, `trailing`	Precise period filtering. Repeat or send CSV.
`statement_type`	`income_statement`, `balance_sheet`, `cash_flow`	Returns metrics assigned to the selected standard sections. Repeat or send CSV.
`metric`	standard metric names	Returns only selected metrics. Repeat or send CSV.
`ratio`	standard ratio names	Returns only selected ratios. Repeat or send CSV.
`latest_only`	boolean	Returns the newest reported period and, if requested, newest trailing period.
`display_currency`	`native` or ISO currency	Keeps reported currency or converts monetary values for display.
`reported_currency`	ISO currency	Selects one native reported currency; valid only with `display_currency=native`.
`with_ratios`	boolean	Enables calculated ratios and valuation measures.
`include_trailing`	boolean	Enables derived trailing-twelve-month periods.
`include_sources`	boolean	Includes the filing source for each metric.
`source_detail`	`reference`, `full`	Chooses compact identifiers or complete public source evidence.
`include_metadata`	boolean	Embeds selected definitions; otherwise use the catalog endpoint.

period_family offers more precise choices than granularity. If you use both, make them consistent.

Scope and subject selection

Financial filings can report Group and Company figures together, or parallel subjects such as Group, Company, and Bank. First request scope=auto, then use available_scopes to discover valid combinations.

GET /v1/financials/statements?ticker=ACCESSCORP&country_code=NG&scope=separate

If an option includes a non-null scope_label, send that exact value with its scope. Do not treat the most recently observed label as permanently valid. Reporting scopes can change between filing eras.

Efficient integration pattern

Resolve a ticker once and store company.id.
Fetch and cache the metric catalog by catalog_version.
Use latest_only, statement_type, metric, and ratio for product views.
Set include_sources=false until a user requests evidence.
Use exact reported-table endpoints when standard metric names do not meet your needs.