Mapping API

To resolve a ticker into a full company profile, use the ticker mapping endpoint at /mapping/ticker/<TICKER> and place the ticker in the path (for example /mapping/ticker/TSLA). The endpoint returns an array of company records that have ever traded under that symbol, each with the company name (name), CIK (cik), CUSIPs (cusip), listing exchange (exchange), security category (category), sector and industry (sector, industry), SIC classification (sic, sicSector, sicIndustry), operating currency (currency), headquarters location (location), a delisted flag (isDelisted), and a stable internal identifier (id).

Because the response is an array, the same ticker may resolve to more than one entry — for example a currently listed common stock and a previously delisted security that reused the symbol. In that case, the delisted flag (isDelisted) distinguishes the active record from the historical ones.

To find the ticker for a company you already identify by CIK, use the CIK mapping endpoint at /mapping/cik/<CIK> and place the numeric CIK in the path (for example /mapping/cik/1318605 for Tesla). The endpoint returns an array of company records linked to that CIK; the ticker symbol is in the ticker field (ticker) on each record.

A single CIK can map to several entries when the issuer has more than one listed security (for example multiple share classes or warrants), so iterate over the returned array and use the security category (category) and the delisted flag (isDelisted) to pick the entry you want.

To map a CUSIP to its issuer, use the CUSIP mapping endpoint at /mapping/cusip/<CUSIP> with the nine-character CUSIP in the path (for example /mapping/cusip/88160R101). The endpoint returns an array of company records that identify the issuer by name (name), CIK (cik), and ticker (ticker), and include the full list of CUSIPs associated with that issuer in the CUSIP field (cusip).

If the CUSIP belongs to a security that has since been restructured, the matching record may carry a different current CUSIP in the CUSIP field (cusip) than the one you queried with, and the delisted flag (isDelisted) tells you whether the security still trades.

To search by company name, use the name mapping endpoint at /mapping/name/<NAME> with the (URL-encoded) name fragment in the path (for example /mapping/name/Tesla). The endpoint returns an array of companies whose name (name) matches the search term, each accompanied by its ticker (ticker), CIK (cik), CUSIPs (cusip), exchange (exchange), and the other standard mapping fields.

Because the response is an array, partial or ambiguous names can return several candidates; narrow them down by inspecting fields such as the listing exchange (exchange), the security category (category), or the delisted flag (isDelisted).

To list every company on a given exchange, use the exchange listing endpoint at /mapping/exchange/<EXCHANGE> with the exchange code in the path (for example /mapping/exchange/NASDAQ). The endpoint returns an array of company records carrying the standard mapping fields including the company name (name), ticker (ticker), CIK (cik), exchange (exchange), security category (category), and the delisted flag (isDelisted).

The array includes both currently listed and previously delisted companies tied to that exchange, so filter on the delisted flag (isDelisted) — it should be false — to keep only securities that still trade.

To list every company in a sector, use the sector listing endpoint at /mapping/sector/<SECTOR> with the sector name in the path (for example /mapping/sector/Consumer%20Cyclical). The endpoint returns an array of company records whose sector field (sector) matches the requested value, each accompanied by the company name (name), ticker (ticker), CIK (cik), industry (industry), listing exchange (exchange), security category (category), and the delisted flag (isDelisted).

If you want only currently trading names, drop the entries where the delisted flag (isDelisted) is true.

To pull the universe of companies in a single industry, use the industry listing endpoint at /mapping/industry/<INDUSTRY> with the industry name in the path (for example /mapping/industry/Auto%20Manufacturers). The endpoint returns an array of company records whose industry field (industry) matches the requested value, each carrying the name (name), ticker (ticker), CIK (cik), sector (sector), exchange (exchange), security category (category), and the delisted flag (isDelisted). The dataset covers 175 industries.

To restrict the result to currently trading companies only, keep records where the delisted flag (isDelisted) is false.

To check whether a ticker still trades, look at the delisted flag (isDelisted) on the company record returned by the ticker mapping endpoint at /mapping/ticker/<TICKER>. The value of isDelisted should be false for an active security and true for a delisted one.

Because a ticker can be reused, the endpoint may return more than one record for the same symbol — for example one historical entry where the delisted flag (isDelisted) is true and a current entry where it is false. Walk through the returned array and pick the entry whose delisted flag matches the status you care about.

To list every CUSIP a company has carried, use any mapping endpoint that resolves the issuer — for example the CIK mapping endpoint at /mapping/cik/<CIK> or the ticker mapping endpoint at /mapping/ticker/<TICKER> — and read the CUSIP field (cusip) on the returned record. The field is a single string that holds one or more CUSIPs delimited by spaces, such as 054748108 92931L302 92931L401; split on whitespace to obtain the individual CUSIPs.

For a bulk view across all issuers, the CIK-to-CUSIP bulk file at /bulk/mapping/cik-to-cusip returns a JSON object whose keys are CIKs and whose values are arrays of every CUSIP linked to that CIK.

To determine the primary exchange for a security, read the exchange field (exchange) on the company record returned by the ticker mapping endpoint at /mapping/ticker/<TICKER> or the CIK mapping endpoint at /mapping/cik/<CIK>. The value is the main listing venue such as NASDAQ or NYSE.

If the endpoint returns more than one record for the same identifier (for example because the symbol has been reused), use the delisted flag (isDelisted) to select the currently active row before reading the exchange field (exchange).

To tell what kind of security a ticker represents, read the security category field (category) on the company record returned by the ticker mapping endpoint at /mapping/ticker/<TICKER>. The value is a human-readable label such as Domestic Common Stock, and the dataset also covers preferred stocks, ADRs, warrants, exchange traded funds, notes, and derivatives.

When a single ticker resolves to multiple records, each record carries its own category field (category) so you can pick the share class or instrument you want without ambiguity.

To get the four-digit SIC code for a company, use the ticker mapping endpoint at /mapping/ticker/<TICKER> or the CIK mapping endpoint at /mapping/cik/<CIK> and read the SIC field (sic) on the returned record (for example 3711 for an auto manufacturer). The record also carries the human-readable SIC sector (sicSector) and SIC industry (sicIndustry) names so you can label the code without an external lookup.

The SIC code reproduces the EDGAR industry classification, which lets you join the mapping output against any other endpoint that filters by SIC.

To look up a company's headquarters, read the location field (location) on the company record returned by any mapping endpoint that resolves the issuer — for example the ticker mapping endpoint at /mapping/ticker/<TICKER> or the CIK mapping endpoint at /mapping/cik/<CIK>. The value is a short string such as California; U.S.A.

The field reflects the headquarters reported for the issuer, not the exchange's location or the place of incorporation.

To get the operating currency for a security, read the currency field (currency) on the company record returned by the ticker mapping endpoint at /mapping/ticker/<TICKER> or the CUSIP mapping endpoint at /mapping/cusip/<CUSIP>. The value is an ISO currency code such as USD.

When a single issuer trades on more than one venue, the array can include separate entries with different currencies, which you can use to normalize prices across cross-listed lines.

To download the full CIK-to-ticker mapping in one file, use the bulk endpoint at /bulk/mapping/cik-to-ticker. It returns a JSON object whose keys are CIKs and whose values are arrays of tickers associated with that CIK, for example a key 7789 with the value ["ASB", "ASB-PE", "ASB.WS"].

The bulk file is regenerated daily between 1:00 AM and 5:00 AM and contains both currently listed and previously delisted entities, so it is appropriate as a complete snapshot for offline use.

To get the full ticker-to-CIK mapping as a single download, use the bulk endpoint at /bulk/mapping/ticker-to-cik. It returns a JSON object whose keys are tickers and whose values are arrays of CIKs that have traded under that ticker — for example AAPL mapping to ["320193"] and MSFT mapping to ["789019"].

Most tickers map to a single CIK, but the array structure accommodates cases where a symbol has been reused by different issuers over time. The bulk file is refreshed daily between 1:00 AM and 5:00 AM.

To get every CUSIP-to-CIK relationship in one file, use the bulk endpoint at /bulk/mapping/cusip-to-cik. It returns a JSON object whose keys are CUSIPs and whose values are arrays of CIKs linked to that CUSIP, for example 02079K107 mapping to ["1652044"].

The file is regenerated daily between 1:00 AM and 5:00 AM and covers both active and inactive securities, which makes it suitable for reconciling a portfolio against current and historical EDGAR entities.

To pull the full CUSIP-to-ticker mapping in one shot, use the bulk endpoint at /bulk/mapping/cusip-to-ticker. It returns a JSON object whose keys are CUSIPs and whose values are arrays of tickers linked to that CUSIP — for example 02079K107 and 38259P706 both mapping to ["GOOG"].

Because a single issuer can have several CUSIPs that all back the same ticker (for example different share classes), multiple keys in the file can resolve to the same ticker. The file is refreshed daily between 1:00 AM and 5:00 AM.

To avoid one-by-one queries, use the bulk endpoint at /bulk/mapping/cik-to-cusip. It returns a JSON object whose keys are CIKs and whose values are arrays of every CUSIP associated with that CIK — for example 1571996 mapping to ["24703L202", "24703L103"].

Issuers with multiple share classes or restructured securities show up as keys with array values of length greater than one, so a single pass over the file yields every CIK-to-CUSIP relationship. The file is refreshed daily between 1:00 AM and 5:00 AM.

To enrich a watchlist with CUSIPs, use the bulk endpoint at /bulk/mapping/ticker-to-cusip. It returns a JSON object whose keys are tickers and whose values are arrays of CUSIPs that back that ticker — for example GOOG mapping to ["02079K107", "38259P706"] and GOOGL mapping to ["02079K305", "38259P508"].

Tickers with more than one share class or with restructured securities have arrays longer than one. The file is refreshed daily between 1:00 AM and 5:00 AM.

The mapping endpoints at /mapping/... and the bulk endpoints at /bulk/mapping/... accept two equivalent authentication methods. You can set the Authorization HTTP header to your API key, or you can attach the key as a query string parameter named token on the request URL (for example /mapping/cik/1318605?token=YOUR_API_KEY).

Both strategies are accepted on every mapping endpoint, so the choice is purely a matter of how you prefer to pass credentials in your client.

To compare a company's editorial sector classification against its EDGAR/SIC classification, look at both pairs of fields on the company record returned by the ticker mapping endpoint at /mapping/ticker/<TICKER> or the CIK mapping endpoint at /mapping/cik/<CIK>. The sector and industry fields (sector, industry) carry values such as Consumer Cyclical and Auto Manufacturers, while the SIC-derived fields (sicSector, sicIndustry) carry the corresponding regulatory labels such as Manufacturing and Motor Vehicles & Passenger Car Bodies. The four-digit SIC code itself sits in the SIC field (sic).

The two classifications cover different needs — the sector and industry fields (sector, industry) are useful for market-style grouping, while the SIC fields (sic, sicSector, sicIndustry) align with the regulator's own coding and are the fields to use when joining mapping data against filings indexed by SIC.

The ticker mapping endpoint at /mapping/ticker/<TICKER> always returns an array, even when a symbol is unambiguous, so the multi-company case is just a matter of iterating over the returned records. Each record carries its own delisted flag (isDelisted), CIK (cik), security category (category), and exchange (exchange), so you can pick the right entry by filtering on those.

A common pattern is to keep records where the delisted flag (isDelisted) is false to get the currently trading entity, and to fall back to entries where the delisted flag is true only when you need the historical issuer that used to trade under that symbol.

To find every CIK that maps to more than one ticker, use the bulk endpoint at /bulk/mapping/cik-to-ticker and inspect the values, which are arrays of tickers keyed by CIK. Keep the entries whose ticker array has a length greater than one — for example a key 7789 whose value is ["ASB", "ASB-PE", "ASB.WS"] represents an issuer with multiple share classes or related instruments under the same CIK.

The bulk file covers both currently listed and previously delisted entities, so the result includes historical multi-ticker CIKs as well. It is refreshed daily between 1:00 AM and 5:00 AM.

To list issuers with more than one CUSIP, use the bulk endpoint at /bulk/mapping/cik-to-cusip and keep the entries whose CUSIP array has a length greater than one. For example a key 1571996 whose value is ["24703L202", "24703L103"] represents an issuer that carries two CUSIPs, typically for distinct share classes or for a restructured security.

As an alternative, the per-issuer mapping endpoints — for example /mapping/cik/<CIK> or /mapping/ticker/<TICKER> — return the CUSIP field (cusip) as a space-delimited string, and any value containing a space identifies a multi-CUSIP issuer.

To confirm that two tickers map to the same CIK, use the bulk endpoint at /bulk/mapping/ticker-to-cik and look up each ticker as a key — the value is an array of CIKs for that ticker, and matching arrays mean a shared issuer. For Alphabet, both GOOG and GOOGL resolve to the same CIK 1652044.

Alternatively, you can call the ticker mapping endpoint at /mapping/ticker/<TICKER> once per share class and compare the CIK field (cik) on the returned records; the per-record CUSIP field (cusip) and security category (category) make it straightforward to see which entry is which share class.

The mapping database is updated daily with the latest information on currently listed and delisted companies. The bulk download files at /bulk/mapping/... are regenerated daily between 1:00 AM and 5:00 AM, which gives you a clear window for scheduling a cache refresh.

The per-issuer endpoints at /mapping/... read from the same daily-updated database, so any cached lookup older than one business day is potentially stale.

Even when CUSIPs change after a restructuring, the CUSIP mapping endpoint at /mapping/cusip/<CUSIP> accepts the historical CUSIP and resolves it back to the issuer. The returned company record carries the issuer's CIK (cik), name (name), ticker (ticker), and the current set of CUSIPs in the CUSIP field (cusip) as a space-delimited string, so you can compare the CUSIP you queried with against the up-to-date list.

If the queried CUSIP no longer appears in the CUSIP field (cusip) on the returned record, the security has been restructured and replaced by the CUSIPs that the field now lists. The delisted flag (isDelisted) tells you whether the issuer's current security still trades.

Every company record returned by the mapping endpoints carries a stable internal identifier in the id field — a hexadecimal string such as e27d6e9606f216c569e46abf407685f3. Read that field from the response of any mapping endpoint, for example the ticker mapping endpoint at /mapping/ticker/<TICKER> or the CIK mapping endpoint at /mapping/cik/<CIK>, and use it as the primary key in your own database.

Unlike the ticker (ticker), which can be reused, or the CUSIP (cusip), which can change with restructurings, the internal identifier (id) is intended to remain stable across such events.

To build a cross-exchange list of ETFs and ETNs, call the exchange listing endpoint at /mapping/exchange/<EXCHANGE> once per US exchange (for example NASDAQ, NYSE, and the others present in your universe) and filter the returned records on the security category field (category). The mapping dataset covers ETFs, ETNs, and ETDs alongside common and preferred stocks, ADRs, and warrants, so the category field is the way to isolate the fund-style instruments.

If you want only currently trading funds, keep records where the delisted flag (isDelisted) is false; to combine the per-exchange results, deduplicate on the stable internal identifier (id) or the CIK (cik).