Entities API

Entities is where every workflow starts: turn a ticker, name, or regulator id into a stable company handle you pass to filings, financials, screeners, and charts. You are working with listings we publish — not a live exchange tape and not every security in the world.

Type AAPL and you should get Apple’s US listing. That row is an entity: the issuer (or fund series, or person) plus one traded line. Later tools take the same id.

Names and half-tickers go to Entity Search. A ticker, CIK (SEC Central Index Key), LEI, or FIGI goes to Entity Reference. Entity Securities lists every listing of that issuer. Entity Structure is the legal-entity tree when we have an LEI.

Parameters and examples sit on those operation pages. Filings attach the same company object on Documents.

CoverageCopy Anchor Link

The catalog is the set of listings we publish: global public equities and depositary receipts we carry, ETF and mutual-fund share classes, plus people and private companies that appear in the regulatory filings we ingest. It is not every security in the world, and it is not a live exchange tape — there are no prices here.

You can look someone up with a ticker, CIK, LEI (Legal Entity Identifier), Japan EDINET filer code, FIGI, fund series id, adviser CRD, or (for matching only) ISIN/CUSIP. We never return ISIN or CUSIP. Structure coverage is legal-entity relationship records for LEIs we know; an entity without an LEI has no tree.

New filings and new listings land when the company-securities pipeline republishes. Search and Reference read that snapshot — they do not call the original identifier sources at request time.

Ids you can sendCopy Anchor Link

Every company-scoped tool uses the same resolve step as Entity Reference. Pass id (or Entity Search query) as any of:

A security id (ticker, FIGI) resolves to that listing. An entity id (CIK, LEI, series id) resolves to our primary listing of that issuer or series.

The same id works on Entity Reference, Entity Securities, Entity Structure, Document Search, Fundamentals, and the Financials statement endpoints. Details: Tickers, Identifiers.

The Entity itemCopy Anchor Link

This is the object you keep for a company. Same fields on every endpoint that returns a company — handle it once. The OpenAPI Entity schema is the contract.

What it is. One catalog row at security grain: names, tickers, backlink_url, issuer keys (CIK, LEI, EDINET, CRD, series id, internal id), FIGIs, and category flags. Rows are not grouped by issuer. See Entities and securities.

Where it appears (always the same shape):

• Entity Search results[]
• Entity Reference entity
• Documents entities[] (filers on a filing or uploaded file)
• later groups that attach companies (filings, ownership)

resolved is true on an Entity Reference hit. On a Document stub, resolved is false when the catalog miss left only a CIK or EDINET code. Entity Search omits resolved.

Ids you send vs the item you get. Request id (and Entity Search query) are company/listing ids — see Ids you can send. The item you get back never includes ISIN or CUSIP.

EntityIdentity on Securities, Structure, Fundamentals, and Financials is a subset of the same fields (names, tickers, backlink_url, cik, lei) — a resolve receipt, not a second company object.

When an Entity sits on a Document, additive filing-role fields may be present: filer_type, fy, q. They do not replace Entity fields. See The Document item.

Entities and securitiesCopy Anchor Link

We use entity for the issuer, series, or person, and security for one traded line of that entity.

Apple Inc. is one entity. In the catalog it appears as many securities: the US ordinary line (AAPL US), Class A / Class B if they trade separately, a preferred, an ADR, an OTC quote, a Tokyo listing. Those rows share cik / lei and differ by ticker, FIGI, and venue.

A mutual-fund or ETF series is also an entity (series_id / S000…). Each share class of that series is its own security — Investor, Institutional, Class A — with its own ticker and FIGI, and the same series / entity ids.

A person or private company is usually a single row (there is no listing to split).

Results are not groupedCopy Anchor Link

Every hit is one catalog row at security grain. We do not nest securities under a parent entity. If Apple has five listed lines, Entity Search can return five objects in results. They look related because they share entity ids, not because they are wrapped together.

You use this to answer:

• “What listings exist for this name or CIK?”
• “Which line is our primary — and what are the other classes?”
• “Which identifiers and venue should I pass to the next tool?”

You do not get prices, filings, or financial statements here — only identity, listings, and (on Entity Structure) legal-entity relationships.

There is no public numeric entity id. Identity is the set of keys on the row. Two rows can share a CIK and still differ by full_ticker / exchange_code.

How matches are rankedCopy Anchor Link

The same catalog powers both tools. What you send decides how many rows you see and which one is first.

Security id — ticker, FIGI, composite FIGI, share-class FIGI, ISIN, or CUSIP.

• Entity Search ranks that listing first (then other relevant hits).
• Entity Reference returns that listing.

Entity id — CIK, LEI, EDINET code, CRD, SEC series id, or internal id.

• Entity Search returns the securities of that issuer or series as separate results, ordered from our primary line to less popular listings and share classes.
• Entity Reference returns one row: that primary security.

Primary is the line we treat as the default profile: ordinary common or ADR ahead of preferred, warrant, unit, or rights; US composite tape ahead of a local exchange or OTC quote; then listing quality and popularity. For funds and ETFs the same order prefers the primary share class of the series over secondary classes.

Examples:

• query=0000320193 (Apple’s CIK) on Entity Search → AAPL US first, then other Apple lines.
• id=0000320193 on Entity Reference → AAPL US only.
• query=AAPL or id=AAPL US → the Apple US ordinary security, because the needle is a ticker.

Entity Search vs Entity ReferenceCopy Anchor Link

Entity Search is autocomplete. It scores name and identifier prefixes and returns a varied page so you can scan the primary listing plus other classes, foreign lines, and nearby names. Use it when the text is a name, a partial ticker, or you want the neighborhood around an id.

Entity Reference is an identifier lookup. Pass a known id and get exactly one row — or entity: null if nothing matched (that is not an error). Use it when you already have a ticker, CIK, LEI, FIGI, series id, or CRD.

Entity Securities takes the same id, resolves the issuer or series, and returns every catalog listing of that entity — not an autocomplete page. Primary ordinary / US line first, then other classes and venues. Each item is slim: name, tickers, venue, FIGIs, OpenFIGI type, active flag.

Entity Structure takes one id and returns the legal-entity hierarchy. scope=below puts the requested entity at level 1 and lists entities under it. scope=ultimate starts at the ultimate parent and returns the full subordinate tree. Nodes are flat: reconstruct the tree with parent_lei and level. A node always has legal-entity metadata; catalog name / ticker / backlink are filled when we have that LEI.

Later tools that need “any id → the keys we query other tables with” use the same resolve step Entity Securities and Entity Structure use: accept a ticker, CIK, LEI, FIGI, or series id, then continue with the issuer ids we resolved.

If you pass category on Entity Reference, only that type is considered. Entity Search category=ALL (the default) mixes types by relevance.

CategoriesCopy Anchor Link

Entity Search category=ALL mixes types by relevance. Entity Reference does not accept ALL — omit category or pass one of the five types.

A fund row becomes ETF when it is an ETP / closed-end fund or the name contains an ETF token; otherwise it is FUND.

How the catalog is builtCopy Anchor Link

Rows come from the company securities pipeline — the same process that builds the site catalog. At a high level:

1. Collect identifiers from regulatory and market sources: LEI records, SEC (CIK, fund series), Japan EDINET, OpenFIGI (FIGI / exchange / security type), fund holdings (N-PORT), and market-data profiles.
2. Reconcile company ↔ security. Multiple sources can disagree. The pipeline scores and consensus-maps issuer keys to listing keys so a CIK, LEI, and ticker land on the same company when the evidence agrees.
3. Expand to listing rows. One issuer or series becomes one row per visible security. Names, tickers, and categories are attached here. We also mark which line is primary.
4. Publish search and reference indexes. Entity Search ranks name/ticker prefixes with a quality bias (US composite, ordinary share, primary line). Entity Reference is an exact lookup on catalog identifiers.

Search, Reference, and Securities read a published snapshot of that catalog. They do not call the source vendors at request time.

Entity Structure reads legal-entity relationship records at request time (who consolidates whom, branches, fund-manager links), then attaches catalog identity for LEIs we know. An entity without an LEI has no hierarchy: entity is still returned, has_relationships is false, and nodes is empty.

TickersCopy Anchor Link

Tickers on Alpha Analyst are not Yahoo suffixes (AAPL.O) and not Bloomberg yellow keys (AAPL US Equity).

How we write themCopy Anchor Link

full_ticker is the normalized symbol, then a space, then an optional Bloomberg code:

• If our price for that line is the US consolidated tape (aggregated NBBO-style bid/ask), we append the composite code US — AAPL US.
• If our price is exchange-specific, we append that venue’s Bloomberg exchange code — SAP GY, 7203 JT.
• If there is no composite or exchange code, full_ticker is the bare symbol.

normalized_ticker is the same symbol without that suffix. Class letters stay on the symbol (BRK-B).

exchange_code and composite_code are the Bloomberg / OpenFIGI venue schema (exchCode / composite codes). US is the US composite. UW is Nasdaq, UN is NYSE, GY is Xetra, JT is Tokyo, and so on.

How to send themCopy Anchor Link

Entity Search query and the id on Entity Reference, Entity Securities, and Entity Structure accept the same ticker spellings:

A trailing Bloomberg market-sector word (Equity, Corp) is ignored if you paste a terminal ticker.

Do not send MIC codes or Yahoo suffixes as the venue part.

What the input matchesCopy Anchor Link

Needles are case-insensitive.

Entity Search (query) is a prefix / relevance lookup against:

• Display names (name / name_short)
• Tickers in both input styles above (full_ticker and normalized_ticker)
• Entity ids: CIK, LEI, EDINET code, CRD, SEC series id, internal id
• Security ids: FIGI, composite FIGI, share-class FIGI
• ISIN and CUSIP (match only)

Entity Reference, Entity Securities, and Entity Structure (id) are an exact match against the same identifier families (not a name search). A venue suffix on a ticker (AAPL US, SAP-GY) prefers the listing whose composite_code or exchange_code equals that code. Securities and Structure then continue from the issuer or series behind that row.

IdentifiersCopy Anchor Link

Entity (issuer / series) keysCopy Anchor Link

These describe the company, fund series, or person. Several securities can share them. More may be added later as sources expand.

• cik — SEC Central Index Key, zero-padded when present (0000320193)
• lei — Legal Entity Identifier (20 characters) when known
• edinet_code — Japan EDINET filer code
• crd_number — IAPD CRD for advisers
• series_id — SEC investment-company series id (the S000… id on N-1A / N-PORT). This is the series, not the class/contract id. See the SEC’s series and class information
• internal_id — Assigned by us when the row has none of the public entity ids above

Security (listing) keysCopy Anchor Link

These distinguish one traded line from another.

• full_ticker / normalized_ticker — see Tickers
• figi — Trading-venue FIGI: one instrument on one venue
• composite_figi — Composite FIGI: same instrument across venues in one country/market
• share_class_figi — Share Class FIGI: same share class globally

OpenFIGI also publishes sec_type, sec_type2, and market_sector on the row.

ISIN and CUSIP (input only)Copy Anchor Link

You may send an ISIN or CUSIP as Entity Search query or as id on Entity Reference, Entity Securities, and Entity Structure. We do not return ISINs or CUSIPs. Redistributing those identifiers in API responses is not permitted under our licensing.

NamesCopy Anchor Link

name and name_short come from the same catalog name pipeline.

1. A merged name is picked from regulatory and market sources (SEC, EDINET, LEI legal names, fund series/class, OpenFIGI security name, and similar), then capitalization is normalized.
2. name_short is that merged name.
3. name is the merged name plus an OpenFIGI type suffix when the security name encodes a class or instrument kind — Class A, Class B, ADR, GDR, preferred, and similar. That is why name can be longer than name_short on the same row.

Use name when you want the full line label. Use name_short for compact UI.

Profile linkCopy Anchor Link

backlink_url is the public profile on Alpha Analyst: https://alpha-analyst.com + the category path + the row slug. Examples: https://alpha-analyst.com/stocks/apple, https://alpha-analyst.com/etfs/spy.

Legal-entity structureCopy Anchor Link

Entity Structure is a legal-entity tree, not a list of listings. Apple the issuer is one LEI; AAPL US and APC GY are securities of that same legal entity and do not appear as separate nodes. Subsidiaries, branches, and fund-manager links are other LEIs.

relationship_type is the type to the parent: IS_DIRECTLY_CONSOLIDATED_BY, IS_INTERNATIONAL_BRANCH_OF, IS_FUND-MANAGED_BY, IS_SUBFUND_OF, IS_FEEDER_TO. Ultimate-consolidation records are used as metadata while walking the graph; the tree hops are the direct structural types. is_inactive is 1 when that relationship is INACTIVE or the LEI record itself is inactive.

scope=below matches “entities under this id.” scope=ultimate matches “full tree from the top parent,” including siblings of the entity you asked for. level and active filter the flat nodes array; the requested entity is kept when active would otherwise drop it.

Response shapeCopy Anchor Link

Entity Search returns { query, category, limit, offset, results }. Entity Reference returns { id, category, entity }. Entity Securities returns { id, entity, count, securities }. Entity Structure returns { id, scope, level, active, entity, center_lei, ultimate_parent_lei, has_relationships, count, nodes }. Search and Reference do not group rows by issuer and do not return peers. entity on a Reference hit always has resolved: true. On Securities and Structure, entity is a slim identity echo (or null on a miss). The company object itself is the Entity item — same fields on Search, Reference, and Documents entities[].

Fields on each rowCopy Anchor Link

These are the public keys. Empty strings mean “not known for this row,” not an error.

GuidesCopy Anchor Link