Company reference data

A listing's profile, analyst estimates, earnings and dividend calendar, and corporate actions. How to address the listing is on Stocks and ETFs. Every field is described in the API reference.

Routes

what	route
profile	GET /v1/securities/{symbol}/profile
analyst consensus	GET /v1/securities/{symbol}/analyst
earnings and dividend calendar	GET /v1/securities/{symbol}/calendar
corporate actions	GET /v1/securities/{symbol}/corporate-actions

Freshness and missing values

Profile, analyst, and calendar data state their freshness in a dataset_status block (on a calendar, earnings_status and dividends_status): outcome is complete, partial, or not_published, and refreshed_at is when it was established. outcome is null with temporarily_unavailable when no result was ever established.

Every null value field says why in field_states.

Profile

On other routes: the 52-week range and average volume in /quote, moving averages in /technicals, the consensus and EPS in /analyst, and splits in /corporate-actions. Fractions, multiples, and percents follow Numbers and rounding.

Share counts and market cap

shares_outstanding is in units of the quoted security: for a depositary receipt, receipt-equivalent shares; for a multi-class issuer, this class's count.

market_cap states its basis in market_cap_basis:

market_cap_basis	meaning
last_close_x_shares_outstanding	this listing's close times shares_outstanding, with the close's date in market_cap_price_date
source_stated	a stated figure; for a multi-class issuer it can count every class

For a market cap at the current price, use /quote. A cap on an unconfirmed close is marked (quality limits on a price).

Currency

financial_currency is the currency of the company's financial statements. Nothing is converted.

Analyst estimates

recommendation is one of strong_buy, buy, hold, underperform, sell. ratings_status says whether the rating distribution was published, not_published, or unavailable.

number_of_analysts counts the opinions behind the consensus and the price targets; ratings_total is the rating distribution's own total. They can differ, so state a breakdown against ratings_total.

The price targets carry price_basis: null with not_published: do not mix them with either basis of /history.

trailing_eps and forward_eps are in instrument.currency.

Earnings calendar

The calendar carries the event's date and the consensus estimates (eps_estimate, revenue_estimate), with no reported actuals or surprises. A calendar with no earnings event says why in field_states.earnings: not_published (as for an ETF) or temporarily_unavailable.

The estimates are in earnings.currency.

Dividend calendar

A calendar dividend is the latest stated ex-date, past or upcoming: compare ex_date with today.

Its amount is the /corporate-actions record of the same ex-date, with its cash_basis. It is null with not_published until the distribution is recorded, and with conflicting_assertions when the records for that date disagree.

Corporate actions

/corporate-actions serves the listing's splits and cash distributions, each in its newest version. /history's adjusted prices use these actions.

• A split's value is shares after ÷ shares before (4:1 is 4, a 1-for-10 reverse split 0.1); a cash action's value_unit is cash_per_share.
• cash_basis: split_adjusted means the amount is in post-split share terms: NVDA's $0.04 dividend of 2024-03-05 is 0.004 after its 10:1 split.
• revised is true when an earlier, different assertion of this action is held.
• Conflicting assertions for one ex-date and type are all served, each with field_states.assertion: conflicting_assertions; none is chosen.
• A special dividend is recorded as dividend; spin-offs are not served.

An empty list means no action was recorded, not that no action occurred.

freshness.stale reads the listing's daily bars, not the actions: true when the bars are behind the calendar (the actions are still served), and null with a reason when it cannot be judged.

A listing outside the daily bars' universe is 404 not_maintained, and one with no daily bar yet is 503 temporarily_unavailable (error codes).