Skip to content
oneapi.finance API Reference

Instruments and identifiers

A real-world security has a half-dozen identifiers, each owned by a different party. oneapi.finance exposes the four that matter for application code, and internally maintains a single canonical row per (symbol, exchange) pair.

The identifier zoo

IdentifierIssuerExampleStable across listings?Stable through name changes?
Ticker / symbolExchangeAAPLNoNo (renames happen)
ISINNational Numbering AgenciesUS0378331005YesYes
FIGIOpenFIGI / BloombergBBG000B9XRY4Yes (one per share class+listing)Yes
CIKSEC0000320193Yes (US issuers only)Yes
LEIGLEIFHWUPKR0MPOU8FGXBT394YesYes
MICISO 10383XNAS(identifies exchange, not instrument)n/a

We expose symbol, exchange, isin, figi, and cik on /v1/profile and /v1/symbol_search. We do not currently surface LEI; if you need it, file an issue.

How they relate

A single equity has, simplified:

  • Many tickers (one per exchange it trades on, plus historical renames).
  • One ISIN per share class that survives renames and re-listings.
  • One FIGI per (share-class, listing) combination — i.e. AAPL on NASDAQ has a different FIGI from AAPL on the German XETR composite, even though it is the same underlying share class.
  • One CIK per US-domiciled issuer, regardless of how many tickers or share classes they have.

Concretely, for Apple Inc. you would see:

{
  "symbol": "AAPL",
  "exchange": "NASDAQ",
  "isin": "US0378331005",
  "figi": "BBG000B9XRY4",
  "cik": "0000320193"
}

When to use which

  • Symbol + exchange is the right key for ad-hoc lookup, watchlists, user-facing inputs, and anywhere a human reads a ticker.
  • ISIN is the right key for portfolio-import flows from brokers (most European brokers export ISIN-keyed positions), tax reporting, and cross-listing dedup.
  • FIGI is the right key when you specifically need to distinguish between two listings of the same security or feed into Bloomberg-style systems. The OpenFIGI registry at openfigi.com is free to query and is the canonical source.
  • CIK is the right key for SEC EDGAR-driven workflows: filings, insider transactions, 13F holdings.

Resolution rules

If you pass a symbol with no exchange and we have multiple matches, we apply this priority:

  1. Exact symbol match on a US primary listing (NASDAQ, NYSE).
  2. Exact symbol match on the largest non-US listing by market cap.
  3. Anything else — disambiguate via the suffix or by passing exchange= explicitly.

If you pass an ISIN, we resolve to the primary listing for that ISIN. To get a specific listing for an ISIN, follow up with /v1/symbol_search?query=<ISIN> and pick the row whose exchange matches what you want.

If you pass a CIK, the API returns the primary common stock for that issuer. Multi-class issuers (Alphabet, Berkshire) require a follow-up /v1/symbol_search to pick a specific class.

Renames, mergers, and ticker changes

When an instrument is renamed (FB → META) or absorbed (ATVI into MSFT):

  • Historical time-series queries against the old ticker continue to work for the period it was listed.
  • Quotes and statistics for the old ticker return 404 not_found after the effective date. Use the new ticker.
  • The corporate_actions table (surfaced in future endpoints) records the event with type = 'ticker_change' or 'merger' and the effective date.

We currently do not return a “this ticker became X” hint in the error body for 404s on historical tickers, but it is on the roadmap.

What’s next