Get startedDashboard

Tickers and entities

Map a ticker to the right share class or company on any date, and read entity IDs correctly on every endpoint.

View llms.txt

A ticker is a label that changes hands. An entity_id is a permanent integer that never does. Every endpoint resolves the ticker you send to an entity_id on a date, serves rows keyed by that entity_id, and tells you in meta which one it chose.

This page covers the two kinds of entity_id, share classes, recycled tickers, delisted companies, predecessor and successor links, ambiguous tickers, and requesting data by entity_id instead of by ticker. Examples that read prices or statements more than 12 months back return those rows on paid plans; Free keys read the last 12 months.

Securities and issuers

There are two kinds of entity_id:

  • A security is one tradable share class, such as Apple common stock or Alphabet Class C. Apple common stock is security 10003635.
  • An issuer is the company that files statements with the SEC. Apple Inc. is issuer 1.

/v1/resolve returns both for a ticker. entity_id is the security and issuer_entity_id is the company above it.

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/resolve/AAPL?include=events"
response.json
{
  "data": {
    "AAPL": {
      "entities": [
        {
          "entity_id": 10003635,
          "name": "APPLE INC",
          "entity_type": "corporation",
          "country": "US",
          "figi": "BBG000B9XRY4",
          "cik": "0000320193",
          "entity_grain": "security",
          "issuer_entity_id": 1,
          "share_class": null,
          "instrument_type": "common",
          "exchange": "NASDAQ",
          "ticker_valid_from": "1980-12-12",
          "ticker_valid_to": null
        }
      ]
    }
  },
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": ["AAPL"],
    "tickers_unresolved": [],
    "resolved_as_of": "2026-09-27",
    ...
  }
}

Which id each endpoint uses

Prices, index membership and holdings describe a tradable share class, so they key rows by the security. Statements, metrics and insider filings describe a company, so they key rows by the issuer. Every response states which one it uses, in meta or, on /v1/resolve, on each row.

  • /v1/prices: security. AAPL rows carry entity_id: 10003635. meta.entity_id_grain is "security".
  • /v1/resolve: security, with issuer_entity_id beside it. Each row's entity_grain is "security", or "issuer" when no share class carries the ticker.
  • /v1/search: security, or the issuer when the company has no security on record. AAPL returns 10003635.
  • /v1/index/{index_name} and /v1/index/{index_name}/events: security. AAPL is 10003635 in the S&P 500 roster. meta.entity_id_grain is "security".
  • /v1/holdings: security. meta.entity_id_is is "security".
  • /v1/fundamentals: issuer. AAPL rows carry entity_id: 1. meta.entity_id_basis is "issuer".
  • /v1/metrics: issuer. AAPL rows carry entity_id: 1. meta.entity_id_basis is "issuer".
  • /v1/insiders: issuer. AAPL rows carry entity_id: 1. meta.entity_id_is is "issuer".

The same ticker therefore returns 10003635 from prices and 1 from fundamentals:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period=quarterly&start=2025-12-01&fields=revenue,net_income"
response.json
{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2025-12-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q1",
      "filing_date": "2026-01-30",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 143756,
      "net_income": 42097
    },
    ...
  ],
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": {"AAPL": 1},
    ...
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "view": "latest",
    ...
  }
}

To join prices to statements, map each security to its issuer with issuer_entity_id from /v1/resolve.

Share classes

Each share class is its own security with its own price series, and every class of one company shares one issuer_entity_id. Alphabet Class A (GOOGL) and Class C (GOOG) are two securities under issuer 31223. Berkshire Hathaway Class A (BRK-A) and Class B (BRK-B) are two securities under issuer 942.

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/resolve/GOOGL,GOOG,BRK-A,BRK-B?include=events"
response.json
{
  "data": {
    "GOOGL": {
      "entities": [
        {
          "entity_id": 10030636,
          "name": "ALPHABET INC",
          "entity_grain": "security",
          "issuer_entity_id": 31223,
          "share_class": "A",
          "ticker_valid_from": "2014-04-03",
          "ticker_valid_to": null,
          ...
        }
      ]
    },
    "GOOG": {
      "entities": [
        {
          "entity_id": 10003590,
          "name": "ALPHABET INC",
          "entity_grain": "security",
          "issuer_entity_id": 31223,
          "share_class": "C",
          "ticker_valid_from": "2014-04-03",
          "ticker_valid_to": null,
          ...
        },
        {
          "entity_id": 10030636,
          "name": "ALPHABET INC",
          "entity_grain": "security",
          "issuer_entity_id": 31223,
          "share_class": "A",
          "ticker_valid_from": "2004-08-19",
          "ticker_valid_to": "2014-04-02",
          ...
        }
      ]
    },
    "BRK-A": {
      "entities": [
        {
          "entity_id": 10006133,
          "name": "BERKSHIRE HATHAWAY INC DEL",
          "entity_grain": "security",
          "issuer_entity_id": 942,
          "share_class": "A",
          ...
        }
      ]
    },
    "BRK-B": {
      "entities": [
        {
          "entity_id": 10025221,
          "name": "BERKSHIRE HATHAWAY INC DEL",
          "entity_grain": "security",
          "issuer_entity_id": 942,
          "share_class": "B",
          ...
        }
      ]
    }
  },
  ...
}

GOOG itself shows a class change: the Class A shares carried GOOG from 2004-08-19 to 2014-04-02, and the Class C shares have carried it since 2014-04-03. A price request for GOOG with a window before April 2014 therefore returns the Class A series, and each row's ticker is the symbol in force on that date:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/GOOG?start=2010-01-04&end=2010-01-05&fields=close"
response.json
{
  "data": [
    {
      "entity_id": 10030636,
      "ticker": "GOOG",
      "entity_name": "ALPHABET INC",
      "gics_sector": "Communication Services",
      "date": "2010-01-04",
      "close": 626.75,
      "price_basis": "trade"
    },
    ...
  ],
  "meta": {
    ...
    "historical_resolution": {
      "GOOG": {
        "entity_id": 10030636,
        "current_entity_id": 10003590,
        "as_of": "2010-01-05"
      }
    },
    ...
  }
}

Request both classes by entity_id to get two series with two different closes:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices?entity_id=10030636,10003590&start=2026-09-25&end=2026-09-25&fields=close"
response.json
{
  "data": [
    {
      "entity_id": 10003590,
      "ticker": "GOOG",
      "entity_name": "ALPHABET INC",
      "gics_sector": "Communication Services",
      "date": "2026-09-25",
      "close": 341.08,
      "price_basis": "trade"
    },
    {
      "entity_id": 10030636,
      "ticker": "GOOGL",
      "entity_name": "ALPHABET INC",
      "gics_sector": "Communication Services",
      "date": "2026-09-25",
      "close": 343.92,
      "price_basis": "trade"
    }
  ],
  "meta": {
    "tickers_requested": [],
    "tickers_resolved": {},
    "tickers_unresolved": [],
    "entity_ids_requested": [10030636, 10003590],
    "entity_ids_unresolved": [],
    "entity_ids_received_as": {
      "10003590": "security_id",
      "10030636": "security_id"
    },
    "entity_id_grain": "security",
    ...
  }
}

Class ticker spellings

Class tickers resolve in dot and dash form when the spelling names one security. Rows always print the dash form, such as BRK-B.

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/BRK.B,BRK-B?start=2026-09-25&end=2026-09-25&fields=close"
response.json
{
  "data": [
    {
      "entity_id": 10025221,
      "ticker": "BRK-B",
      "entity_name": "BERKSHIRE HATHAWAY INC DEL",
      "gics_sector": "Financials",
      "date": "2026-09-25",
      "close": 505.48,
      "price_basis": "trade"
    }
  ],
  "meta": {
    "tickers_requested": ["BRK.B", "BRK-B"],
    "tickers_resolved": {
      "BRK.B": 10025221,
      "BRK-B": 10025221
    },
    "tickers_unresolved": [],
    "resolved_via": {
      "BRK.B": "security_alias",
      "BRK-B": "security_alias"
    },
    ...
  }
}

Two spellings of one security return one series. The same happens on issuer endpoints: /v1/fundamentals/GOOGL,GOOG maps both tickers to issuer 31223 in meta.tickers_resolved, returns the company's rows once, and fills the row ticker with the later of the two requested tickers (GOOG for GOOGL,GOOG, GOOGL for GOOG,GOOGL).

Recycled tickers

A recycled ticker has belonged to more than one company. GM belonged to General Motors Corporation until 2009-06-01, and has belonged to General Motors Company since 2010-11-18. Without date, /v1/resolve lists every holder, the current holder first:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/resolve/GM?include=events"
response.json
{
  "data": {
    "GM": {
      "entities": [
        {
          "entity_id": 10001879,
          "name": "GENERAL MOTORS CO",
          "cik": "0001467858",
          "entity_grain": "security",
          "issuer_entity_id": 5,
          "exchange": "NYSE",
          "ticker_valid_from": "2010-11-18",
          "ticker_valid_to": null,
          ...
        },
        {
          "entity_id": 10001629,
          "name": "GENERAL MOTORS CORP",
          "cik": "0000040730",
          "entity_grain": "security",
          "issuer_entity_id": 4,
          "exchange": "NYSE",
          "ticker_valid_from": "1962-07-02",
          "ticker_valid_to": "2009-06-01",
          ...
        }
      ]
    }
  },
  ...
}

Pass date to get only the holder on that date:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/resolve/GM?include=events&date=2005-06-30"
response.json
{
  "data": {
    "GM": {
      "entities": [
        {
          "entity_id": 10001629,
          "name": "GENERAL MOTORS CORP",
          "entity_type": "corporation",
          "country": "US",
          "figi": null,
          "cik": "0000040730",
          "entity_grain": "security",
          "issuer_entity_id": 4,
          "share_class": null,
          "instrument_type": "common",
          "exchange": "NYSE",
          "ticker_valid_from": "1968-01-02",
          "ticker_valid_to": "2009-06-01"
        }
      ]
    }
  },
  "meta": {
    "tickers_requested": ["GM"],
    "tickers_resolved": ["GM"],
    "tickers_unresolved": [],
    "resolved_as_of": "2005-06-30",
    "tickers_resolved_via": {"GM": "security_alias"},
    ...
    "as_of": "2005-06-30",
    ...
  }
}

With date, ticker_valid_from and ticker_valid_to describe the recorded span that contains that date. Without date, adjacent spans of one holder are merged: the same security shows 1962-07-02 to 1968-01-01 for date=1965-01-04, and 1962-07-02 to 2009-06-01 without date.

Data endpoints resolve the ticker on the end date of your request, or on as_of when you pass it to fundamentals or metrics. How each endpoint resolves, below, lists the dates tried when that date is missing or names no security. A 2005 price window for GM returns the old company, and meta.historical_resolution reports that the served security is not today's holder:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/GM?start=2005-06-27&end=2005-06-30&fields=close"
response.json
{
  "data": [
    {
      "entity_id": 10001629,
      "ticker": "GM",
      "entity_name": "GENERAL MOTORS CORP",
      "gics_sector": "Consumer Discretionary",
      "date": "2005-06-27",
      "close": 33.47,
      "price_basis": "trade"
    },
    ...
  ],
  "meta": {
    "tickers_requested": ["GM"],
    "tickers_resolved": {"GM": 10001629},
    "tickers_unresolved": [],
    "historical_resolution": {
      "GM": {
        "entity_id": 10001629,
        "current_entity_id": 10001879,
        "as_of": "2005-06-30"
      }
    },
    "historical_resolution_note": "Resolved to a previous holder of the ticker: the requested date window ends before the ticker's current holder acquired it. Pass entity_id to pin an entity explicitly.",
    ...
  }
}

In historical_resolution, entity_id is the entity served, current_entity_id is today's holder of the ticker (null when nobody holds it today), and as_of is the date on which the ticker was resolved. Both ids follow the endpoint's scope: securities on /v1/prices, issuers on /v1/fundamentals, /v1/metrics and /v1/insiders. A ticker request never joins two holders into one series: each holder's rows carry its own entity_id.

How each endpoint resolves

Each endpoint tries a fixed list of dates and uses the first date on which the ticker names a security. If no date in the list works, it falls back to the last company that held the ticker.

  • /v1/prices: your end, then your start, then today.
  • /v1/fundamentals and /v1/metrics: your as_of, then end, then start, then today. A date on which the company had no listed security is skipped.
  • /v1/insiders: your end, then the last holder inside your window when you pass both start and end, then start, then today.
  • /v1/holdings: your end, then quarter, then the last holder inside your window, then start, then today.
  • /v1/resolve: your date, or today. Without date, every holder is listed.
  • /v1/search: no date. q matches every ticker and name a security has carried.

The order matters when the ticker changed hands inside your window. With only a start before 2009, GM still resolves to the old company, because start is tried before today:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/GM?start=2005-06-27&limit=2&fields=close"
response.json
{
  "data": [
    {
      "entity_id": 10001629,
      "ticker": "GM",
      "entity_name": "GENERAL MOTORS CORP",
      "gics_sector": "Consumer Discretionary",
      "date": "2005-06-27",
      "close": 33.47,
      "price_basis": "trade"
    },
    ...
  ],
  "meta": {
    ...
    "historical_resolution": {
      "GM": {
        "entity_id": 10001629,
        "current_entity_id": 10001879,
        "as_of": "2005-06-27"
      }
    },
    ...
  }
}

Insider and holdings responses carry historical_resolution at the top level of the body, with an extra via key that names the step that matched. On /v1/insiders its entity_id is the issuer:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/insiders/RTN?end=2020-03-31&limit=1&fields=insider_name,transaction_type"
response.json
{
  "tickers": ["RTN"],
  "historical_resolution": {
    "RTN": {
      "entity_id": 6172,
      "current_entity_id": null,
      "as_of": "2020-03-31",
      "via": "requested_date"
    }
  },
  "historical_resolution_note": "Resolved to a previous holder of the ticker: the requested date window ends before the ticker's current holder acquired it. Pass entity_id to pin an entity explicitly.",
  "data": [
    {
      "entity_id": 6172,
      "ticker": "RTN",
      "entity_name": "RAYTHEON CO",
      "transaction_date": "2020-03-26",
      "filing_date": "2020-03-27",
      "form_type": "4",
      "insider_name": "Wood Michael J",
      "transaction_type": "open_market_sell",
      ...
    }
  ],
  ...
}

How the match is reported

Responses name the method that matched each ticker. The key is resolved_via on /v1/prices and tickers_resolved_via on /v1/fundamentals, /v1/metrics and /v1/resolve. The values are:

  • security_alias: the share class itself carried the ticker on the date. AAPL resolves this way.
  • issuer_alias: the company carried the ticker, and the answer is its one listed share class, or its one listed common stock.
  • security_alias_censored: the company lists several share classes, and the answer is the class that itself last carried the ticker.
  • last_holder: nothing carried the ticker on the dates tried, and the answer is its last holder. TWTR with no dates resolves this way to Twitter.

On /v1/insiders and /v1/holdings, the via key inside historical_resolution names the date step instead, such as requested_date.

Pin the company with entity_id

If your window spans a change of holder, request by entity_id instead of by ticker. The id never moves to another company.

Delisted companies

Delisted, merged and bankrupt companies stay in the data. Their tickers resolve on dates when they traded, their price series end on their last trading day, and meta.delisting reports the terminal event for a series whose last row is on or before that event.

Raytheon Company traded as RTN until 2020-04-02, when it merged with United Technologies. A window that runs past that date returns rows up to the last trading day:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/RTN?start=2020-03-30&end=2020-04-10&fields=close"
response.json
{
  "data": [
    ...
    {
      "entity_id": 10012171,
      "ticker": "RTN",
      "entity_name": "RAYTHEON CO",
      "gics_sector": "Industrials",
      "date": "2020-04-02",
      "close": 116.96,
      "price_basis": "trade"
    }
  ],
  "meta": {
    "tickers_requested": ["RTN"],
    "tickers_resolved": {"RTN": 10012171},
    "tickers_unresolved": [],
    "historical_resolution": {
      "RTN": {
        "entity_id": 10012171,
        "current_entity_id": null,
        "as_of": "2020-03-30"
      }
    },
    ...
    "data_through": "2020-04-02",
    ...
    "delisting": {
      "10012171": {
        "event_date": "2020-04-02",
        "event_type": "merger",
        "delisting_return": -0.003278
      }
    },
    ...
  }
}

Here end (2020-04-10) was after the last trade, so the ticker resolved on start (2020-03-30). current_entity_id is null because no company holds RTN today. delisting_return is a decimal ratio, not a percentage.

Predecessors and successors

/v1/resolve returns succession links from mergers and similar events. Each link names the other company's issuer id, its name, the event type and the event date. Links are one hop: each names a direct predecessor or successor only.

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/resolve/RTX?include=events"
response.json
{
  "data": {
    "RTX": {
      "entities": [
        {
          "entity_id": 10006181,
          "name": "R T X CORP",
          "entity_type": "corporation",
          "country": "US",
          "figi": "BBG000BW8S60",
          "cik": "0000101829",
          "entity_grain": "security",
          "issuer_entity_id": 7749,
          "share_class": null,
          "instrument_type": "common",
          "exchange": "NYSE",
          "ticker_valid_from": "2020-04-03",
          "ticker_valid_to": null,
          "succession": {
            "predecessors": [
              {
                "entity_id": 6172,
                "name": "RAYTHEON CO",
                "event_type": "merger",
                "event_date": "2020-04-02"
              }
            ],
            "successors": []
          }
        },
        {
          "entity_id": 10029019,
          "name": "MERRIMAN HOLDINGS INC",
          ...
          "ticker_valid_from": "2000-07-10",
          "ticker_valid_to": "2003-07-21"
        },
        ...
      ]
    }
  },
  ...
}

RTX is also a recycled ticker: the response lists earlier holders after the current one. The succession block appears only on entities that have at least one link, and when it appears both arrays are present.

The link's entity_id is an issuer id, so it works directly on the issuer endpoints. Raytheon's statements run to its last fiscal year before the merger:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals?entity_id=6172&period=annual&start=2018-01-01&fields=revenue,net_income"
response.json
{
  "data": [
    {
      "entity_id": 6172,
      "ticker": "RTN",
      "entity_name": "RAYTHEON CO",
      "gics_sector": "Industrials",
      "period_end": "2018-12-31",
      "period_type": "annual",
      "fiscal_year": 2018,
      "fiscal_period": "FY",
      "filing_date": "2019-02-13",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 27058,
      "net_income": 2909
    },
    {
      "entity_id": 6172,
      "ticker": "RTN",
      "entity_name": "RAYTHEON CO",
      "gics_sector": "Industrials",
      "period_end": "2019-12-31",
      "period_type": "annual",
      "fiscal_year": 2019,
      "fiscal_period": "FY",
      "filing_date": "2020-02-12",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 29176,
      "net_income": 3343
    }
  ],
  "meta": {
    "tickers_requested": [],
    "tickers_resolved": {},
    "tickers_unresolved": [],
    "entity_ids_requested": [6172],
    "entity_ids_unresolved": [],
    "data_through": "2019-12-31",
    ...
  }
}

Revenue and net income are in millions of USD. On /v1/fundamentals, /v1/metrics and /v1/insiders, rows requested by an issuer's entity_id carry the ticker and entity_name of the issuer's primary listed class, the same labels a request by that class's ticker carries; on /v1/prices, ticker is the symbol in force on the row's date.

The primary listed class is chosen on a date: on /v1/metrics, as_of, otherwise today; on /v1/fundamentals, as_of, else end, and on /v1/insiders, end, otherwise today. A security recorded as delisted by merger into another class of the same issuer is not considered. It is the issuer's one share class that traded in the 30 days up to that date; when several traded, one of the common classes among them; when none traded, one of its common classes, or its only class. Among several, the class with no class letter comes first, then the lowest letter, then the lowest entity_id. It is GOOGL for Alphabet (31223), BRK-A for Berkshire Hathaway (942), TAP-A for Molson Coors (1944) and BF-A for Brown-Forman (1141). Metrics by issuer id are priced on that class.

Ambiguous tickers

A ticker is ambiguous on a date when it names more than one security. BRK names both Berkshire Hathaway classes. When nothing else in the request resolves, /v1/prices, /v1/resolve and /v1/metrics return HTTP 409 with the candidates and "hint": "pass entity_id=":

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/resolve/BRK"
response.json
{
  "error": "ambiguous_ticker",
  "code": "ambiguous_ticker",
  "status": 409,
  "detail": "BRK names more than one security on 2026-09-27. Request by entity_id to choose one.",
  "hint": "pass entity_id=",
  "candidates": {
    "BRK": [
      {
        "entity_id": 10006133,
        "name": "BERKSHIRE HATHAWAY INC DEL",
        "exchange": "NYSE",
        "share_class": "A",
        "last_bar_date": "2026-09-25",
        "valid_from": null,
        "valid_to": null
      },
      {
        "entity_id": 10025221,
        "name": "BERKSHIRE HATHAWAY INC DEL",
        "exchange": "NYSE",
        "share_class": "B",
        "last_bar_date": "2026-09-25",
        "valid_from": null,
        "valid_to": null
      }
    ]
  }
}

The /v1/prices body has the same fields, with hint after candidates. With end=2026-09-25, its detail reads BRK names more than one security on 2026-09-25. Request by entity_id to choose one. Pick a candidate's entity_id and request it with the entity_id parameter.

When other tickers in the request resolve, /v1/prices returns their rows with HTTP 200, lists the ambiguous ticker in meta.tickers_ambiguous and names it in warnings:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/AAPL,BRK?start=2026-09-25&end=2026-09-25&fields=close"
response.json
{
  "data": [
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "date": "2026-09-25",
      "close": 341.07,
      "price_basis": "trade"
    }
  ],
  "meta": {
    "tickers_requested": ["AAPL", "BRK"],
    "tickers_resolved": {"AAPL": 10003635},
    "tickers_unresolved": [],
    "tickers_ambiguous": {
      "BRK": [
        {
          "entity_id": 10006133,
          "name": "BERKSHIRE HATHAWAY INC DEL",
          "exchange": "NYSE",
          "share_class": "A",
          "last_bar_date": "2026-09-25",
          "valid_from": null,
          "valid_to": null
        },
        {
          "entity_id": 10025221,
          "name": "BERKSHIRE HATHAWAY INC DEL",
          "exchange": "NYSE",
          "share_class": "B",
          "last_bar_date": "2026-09-25",
          "valid_from": null,
          "valid_to": null
        }
      ]
    },
    ...
  },
  "warnings": ["BRK names more than one security on that date; pick one from meta.tickers_ambiguous and request it by entity_id"]
}

The other endpoints treat BRK as follows:

  • /v1/metrics returns HTTP 409, as /v1/prices does. In a list with other tickers, it lists BRK in meta.tickers_ambiguous and meta.tickers_unresolved.
  • /v1/fundamentals and /v1/insiders resolve it to the company, issuer 942, because both classes belong to one issuer, and add the warning BRK named more than one share class on that date; served at the company level.
  • /v1/holdings serves every class of the company, each row with its class's ticker, and adds the same warning.

A ticker that names two different companies on the date, such as SFN on 2009-06-30, returns HTTP 409 on /v1/prices, /v1/fundamentals, /v1/metrics, /v1/insiders and /v1/holdings when nothing else in the request resolves.

Requesting by entity_id

Pass entity_id instead of a ticker on /v1/prices, /v1/fundamentals, /v1/metrics, /v1/insiders and /v1/holdings. Leave the ticker out of the path, and separate several ids with commas. Each id counts as one ticker toward your plan's per-request limit: a Free key sending two ids gets HTTP 400 Free tier allows 1 entity_id per request. Upgrade to Pro for up to 100. https://xfinlink.com/pricing. A request that sends both a ticker and entity_id also returns HTTP 400.

Get ids from /v1/resolve, /v1/search, succession links, or the entity_id column of any earlier response. Each endpoint accepts the ids below:

  • /v1/prices: a security id, or an issuer id. An issuer id resolves to the company's one listed security; meta.entity_ids_received_as reports "issuer_id". An issuer with two listed classes, such as Alphabet (31223), returns HTTP 409 with both classes as candidates.
  • /v1/fundamentals and /v1/metrics: an issuer id only. A security id returns no rows.
  • /v1/insiders: a security id or an issuer id. A security id is mapped to its issuer.
  • /v1/holdings: a security id returns that security; an issuer id returns every security of the company.

A security id on an issuer endpoint:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals?entity_id=10003635&period=annual&start=2025-01-01&fields=revenue"
response.json
{
  "error": "not_found",
  "code": "not_found",
  "status": 404,
  "detail": "No matching entities for: 10003635"
}

The same security id on /v1/insiders returns Apple's filings under issuer 1:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/insiders?entity_id=10003635&end=2026-09-24&limit=1&fields=insider_name,transaction_type"
response.json
{
  "tickers": [],
  "entity_ids": [10003635],
  "entity_ids_unresolved": [],
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "transaction_date": "2026-09-22",
      "filing_date": "2026-09-24",
      "form_type": "4",
      "insider_name": "Newstead Jennifer",
      "transaction_type": "open_market_sell",
      ...
    }
  ],
  ...
  "meta": {
    "entity_id_is": "issuer",
    ...
  }
}

An issuer id on /v1/prices for a company with one listed security:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices?entity_id=1&start=2026-09-25&end=2026-09-25&fields=close"
response.json
{
  "data": [
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "date": "2026-09-25",
      "close": 341.07,
      "price_basis": "trade"
    }
  ],
  "meta": {
    ...
    "entity_ids_requested": [1],
    "entity_ids_unresolved": [],
    "entity_ids_received_as": {"1": "issuer_id"},
    "entity_id_grain": "security",
    ...
  }
}

Resolution errors

statuserror codewhen it happenshow to fix
404not_foundNo ticker or id in the request resolves on its endpoint, for example an unknown ticker, or a security id on /v1/metrics: "No matching entities for: 10003635".Check the spelling with /v1/search, use a class ticker such as BRK-B, or pass the issuer id.
409ambiguous_tickerOn /v1/prices, /v1/resolve and /v1/metrics, every ticker in the request names more than one security on the resolution date; on /v1/fundamentals, /v1/insiders and /v1/holdings, every ticker names more than one company. The body lists candidates and hint.On /v1/prices, /v1/insiders and /v1/holdings, send a candidate's entity_id as the entity_id parameter. On /v1/metrics and /v1/fundamentals, request a class ticker such as BRK-B, or send the issuer's entity_id, which Resolve returns as issuer_entity_id.
400bad_requestThe request sends a ticker in the path and the entity_id parameter: "Provide either a ticker in the path or an entity_id parameter, not both."Send one or the other.

See Errors for every error the API returns, and Resolve for every field of /v1/resolve.

Was this page helpful?