Resolve
Map a ticker to every entity that has carried it, with validity dates, classifications, index membership and succession links.
GET /v1/resolve/{ticker} returns every entity that has carried a ticker: its entity_id, name, FIGI and CIK, the dates it carried the ticker, its industry classifications, its membership of the S&P 500, Nasdaq-100 and Dow Jones Industrial Average, and its succession links to predecessor and successor companies. Use it to find the entity_id to pass to Prices, Fundamentals and the other data endpoints, and to see which company held a recycled ticker on a given date.
The response contains no money, share or percentage values. Dates are YYYY-MM-DD strings. entity_id and issuer_entity_id are integers; figi and cik are strings.
Each row states its own grain in entity_grain. On security rows the entity_id names one share class; on issuer rows it names the company. Tickers and entities explains the two.
An API key is optional. Without one, the response omits validity dates, classifications and index membership and carries "restricted": true. See Plan differences below.
Parameters
tickerstrRequiredPath segment. One ticker, or up to 10 comma-separated tickers, on every plan. Case-insensitive. Dot and hyphen class forms both work: BRK.B and BRK-B reach the same share class. A ticker repeated in the list returns one entry.
includestrDefault: "all"Comma-separated sections to add to each row: events (succession links), index (index membership), classifications, or all for the three. Any other value returns 400. index and classifications need a key.
datestrDefault: today (UTC)YYYY-MM-DD. Resolve the ticker as it stood on that date: only holders whose period with the ticker contains the date are returned. No history limit applies on any plan. In the Python client the argument is date_.
Response
The body is an object with data, meta and, without a key, restricted.
| field | type | unit | nullable | description |
|---|---|---|---|---|
data | object | — | no | Keyed by requested ticker, upper-cased and spelled as requested. Each value is {"entities": [...]}, one row per holder. |
meta | object | — | no | Resolution details, described in the meta table below. |
restricted | bool | — | no | true when the request carried no valid key. The field is absent on keyed responses. |
Without date, entities lists the current holder first, then every past holder, most recently ended first. With date, it lists the holder on that date.
Entity fields
| field | type | unit | nullable | description |
|---|---|---|---|---|
entity_id | int | — | no | Share-class id when entity_grain is security; company id when it is issuer. Pass it as entity_id to the data endpoints. |
name | str | — | yes | Entity name as recorded, for example GENERAL MOTORS CO. |
entity_type | str | — | no | corporation, etf or closed_end_fund. Issuer rows, preferreds, ADRs, notes and units are corporation. |
country | str | — | no | Always US. |
figi | str | — | yes | FIGI recorded for the company. Every share class of one company carries the same value: GOOGL and GOOG both return BBG009S3NB30. |
cik | str | — | yes | SEC Central Index Key of the company, 10 digits with leading zeros, for example 0000320193. |
entity_grain | str | — | no | security (one share class) or issuer (the company, where no share class carried the ticker). |
issuer_entity_id | int | — | yes | Company id above the share class. Equal to entity_id on issuer rows. Null where no company record is linked. |
share_class | str | — | yes | Class letter, for example A, B or C. Null for single-class companies and issuer rows. |
instrument_type | str | — | yes | common, adr, etf, cef, preferred, note_etn, unit or structured. Null on issuer rows. |
exchange | str | — | yes | Exchange on the last day the row carried the ticker, or on date (today without date) for the current holder: NASDAQ, NYSE, AMEX, ARCA, BATS or IEX. Null on issuer rows and where no exchange is recorded. |
ticker_valid_from | str | date | yes | First day the entity carried the ticker. Key required. Null when the start is not recorded, and on last_holder rows. |
ticker_valid_to | str | date | yes | Last day the entity carried the ticker. Null while it still carries it, and on last_holder rows. Key required. |
classifications | object | — | no | Industry codes for the company. Key required, and include must contain classifications or all. |
succession | object | — | no | Predecessor and successor links. Present when include contains events or all and the company has at least one link; absent otherwise. Returned with or without a key. |
index_membership | array | — | no | Index membership periods that overlap the period the entity carried the ticker. Key required, and include must contain index or all. Empty array when there are none. |
With date, ticker_valid_from and ticker_valid_to describe the continuous period that contains the date. Without date, they span the first to the last day the entity carried the ticker.
Classifications
Each key is present only when a value is recorded for the company.
| field | type | unit | nullable | description |
|---|---|---|---|---|
sic_code | str | — | no | Standard Industrial Classification code, for example 3711. |
naics_code | str | — | no | North American Industry Classification System code, for example 336110. |
gics_sector | str | — | no | GICS sector name, one of the 11 values listed on Search. |
gics_group | str | — | no | GICS industry group name, for example Automobiles & Components. |
gics_industry | str | — | no | GICS industry name, for example Automobiles. |
gics_sub_industry | str | — | no | GICS sub-industry name, for example Automobile Manufacturers. |
classification_as_of | str | date | no | Date the classification describes. |
Succession links
succession holds two arrays, predecessors and successors. Both are present whenever the object is present, and either can be empty. Links are company to company and one hop: a chain through three companies reads as two links.
| field | type | unit | nullable | description |
|---|---|---|---|---|
entity_id | int | — | no | Company id of the linked company. Pass it to Fundamentals to read that company's own statements. |
name | str | — | no | Name of the linked company. |
event_type | str | — | no | Kind of corporate event: merger, spinoff, de_spac, reverse_merger, reorganisation or redomestication. |
event_date | str | date | no | Date of the event. |
Index membership
| field | type | unit | nullable | description |
|---|---|---|---|---|
index | str | — | no | SP500, DJIA or NDX100. |
index_name | str | — | no | S&P 500, Dow Jones Industrial Average or Nasdaq-100. |
added | str | date | no | First day in the index. |
removed | str | date | yes | Last day in the index. Null while the entity is a member. |
A company can have more than one period in the same index. Index membership returns whole rosters.
Meta
Response metadata explains knowledge_time, as_of and freshness.
| field | type | unit | nullable | description |
|---|---|---|---|---|
tickers_requested | array | — | no | Tickers as parsed from the path, upper-cased, in request order. A repeated ticker appears twice. |
tickers_resolved | array | — | no | Tickers with at least one row in data. |
tickers_unresolved | array | — | no | Tickers with no row: never carried, first carried after date, or shaped as a warrant, unit, right, preferred or other share class than the one that carries them. |
resolved_as_of | str | date | no | Date the tickers were resolved on: date, or today (UTC). |
tickers_resolved_via | object | — | no | Ticker to method, for tickers with a holder on the resolution date: security_alias (the share class carried the ticker), issuer_alias (the company carried the ticker and has one listed share class, or 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) or last_holder (dated requests only: nothing carried the ticker on the date, and the answer is its last holder before the date). Absent when no ticker has a holder on the date. |
tickers_ambiguous | object | — | no | Ticker to candidate list, for tickers that name two or more listed share classes on the date. Present only in a 200 response where another ticker resolved; otherwise the response is 409. |
ambiguous_hint | str | — | no | pass entity_id=. Present with tickers_ambiguous. |
tickers_no_listed_security | object | — | no | Ticker to {issuer_entity_id, name}, for tickers recorded under a company that lists no share class on the resolution date. |
tickers_past_holders_only | array | — | no | Tickers whose rows are all past holders. Requests without date only. |
include | array | — | no | Sections requested. all expands to ["events", "index", "classifications"]. |
entity_id_grain | str | — | no | Reminder that entity_id grain is stated per row in entity_grain. |
knowledge_time | str | UTC timestamp | yes | Newest knowledge time across the datasets used. |
as_of | str | date | no | Equal to date. Present only when date is passed. |
freshness | array | — | no | One {dataset, through, promoted_at} entry per dataset used: identifiers, entities, listings, plus entity_events for events, and, with a key, index_membership for index and classifications for classifications. |
Pagination
Resolve does not paginate. One request returns every holder of up to 10 tickers.
Errors
A multi-ticker request returns 200 when at least one ticker has a row; the other tickers are reported in meta. The errors below apply when no ticker produces a row, or when the request itself is invalid.
| status | error code | when it happens | how to fix |
|---|---|---|---|
400 | bad_request | The path has no ticker after splitting on commas, for example /v1/resolve/,. | Pass at least one ticker. |
400 | bad_request | More than 10 tickers in the path. | Split the list into requests of 10 or fewer. |
400 | bad_request | include contains a value other than events, index, classifications or all. | Use the listed values. |
400 | bad_request | date is not in YYYY-MM-DD form, or is not a real calendar date. | Pass a real calendar date as YYYY-MM-DD. |
401 | unauthorized | A key sent in X-API-Key or api_key is not valid, or a key sent as Authorization: Bearer is revoked or unrecognised. | Send a valid key, or send the request without one. |
404 | not_found | No ticker has a row: each was never carried, was first carried after date, or is shaped as an instrument other than the one that carries it. | Check the spelling, or find the company with Search. |
404 | not_found | Every ticker is recorded under a company that lists no share class on the resolution date. The message names the company's entity_id. | Pass that entity_id to Fundamentals, or resolve without date to see past holders. |
404 | not_found | The path ends at /v1/resolve/ with no ticker segment. | Add a ticker to the path. |
409 | ambiguous_ticker | Every ticker names two or more listed share classes on the date, for example BRK. | Pick a candidate and request by its class ticker (BRK-A, BRK-B) or its entity_id. |
429 | see Rate limits | A request allowance is used up: the plan's, or without a key, the allowance for your IP address. With a key, the plan's row allowance also applies. | Wait for the reset. A request-limit body gives the wait in retry_after_seconds; daily allowances reset at 00:00 UTC and hourly ones at the top of the UTC hour. |
400, too many tickers:
{"error": "bad_request", "code": "bad_request", "status": 400, "detail": "Maximum 10 tickers per request"}400, unknown include (include=foo):
{"error": "bad_request", "code": "bad_request", "status": 400, "detail": "Unknown include: foo"}400, malformed date (date=2024-1-5):
{"error": "bad_request", "code": "bad_request", "status": 400, "detail": "date must be YYYY-MM-DD"}400, no ticker (/v1/resolve/,):
{"error": "bad_request", "code": "bad_request", "status": 400, "detail": "No ticker provided"}404, unknown ticker (/v1/resolve/ZZZZQ):
{"error": "not_found", "code": "not_found", "status": 404, "detail": "No matching entities for: ZZZZQ"}404, no listed share class on the date (/v1/resolve/HES?date=2026-09-01):
{
"error": "not_found",
"code": "not_found",
"status": 404,
"detail": "No listed security on 2026-09-01 for HES: it names HESS CORP (entity_id 315); pass entity_id=315 for issuer-level data."
}409, ambiguous ticker (/v1/resolve/BRK). Each candidate carries entity_id, name, exchange, share_class, last_bar_date (the latest trading day on or before the resolution date), and valid_from and valid_to (the period the share class itself carried the ticker, null when the match came through the company):
{
"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
}
]
}
}Plan differences
Every keyed request returns the same body on every plan, and every plan can resolve up to 10 tickers per request. The one-ticker limit that applies to Free on Prices does not apply here, and date has no history limit on any plan.
- Free: full body, 10 tickers per request, any
date. - Pro: identical to Free.
- Max: identical to Free, including the 10-ticker cap.
- Redistribution: identical to Free, including the 10-ticker cap: 11 tickers return
400. - No key:
ticker_valid_from,ticker_valid_to,classificationsandindex_membershipare omitted,freshnesshas noindex_membershiporclassificationsentry, and the body carries"restricted": true.successionis still returned. A key sent inX-API-Keyorapi_keythat is not valid returns401rather than the restricted body.
Each ticker in the path counts as one request against your plan's daily allowance. Requests without a key are limited per IP address to 40 requests per UTC clock hour and 100 per UTC day, and the response headers report X-RateLimit-Limit-Day: 100 and X-RateLimit-Limit-Hour: 40. Rate limits has the details.
The same GM request without a key:
curl -s "https://api.xfinlink.com/v1/resolve/GM"{
"data": {
"GM": {
"entities": [
{
"entity_id": 10001879,
"name": "GENERAL MOTORS CO",
"entity_type": "corporation",
"country": "US",
"figi": "BBG000NDYB67",
"cik": "0001467858",
"entity_grain": "security",
"issuer_entity_id": 5,
"share_class": null,
"instrument_type": "common",
"exchange": "NYSE"
},
{
"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"
}
]
}
},
"meta": {
"tickers_requested": [
"GM"
],
"tickers_resolved": [
"GM"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_resolved_via": {
"GM": "security_alias"
},
"include": [
"events",
"index",
"classifications"
],
"entity_id_grain": "per row: entity_grain='security' means entity_id is the share-class id; 'issuer' means no share class carries the ticker and entity_id is the issuer id",
"knowledge_time": "2026-09-18T01:59:25Z",
"freshness": [
{
"dataset": "identifiers",
"through": "2026-07-30",
"promoted_at": "2026-09-18T05:17:40Z"
},
...
]
},
"restricted": true
}With a Free key, a two-ticker request returns the full body, including validity dates:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/GM,RTX?include=events"{
"data": {
"GM": {
"entities": [
...
]
},
"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": []
}
},
...
]
}
},
"meta": {
"tickers_requested": [
"GM",
"RTX"
],
"tickers_resolved": [
"GM",
"RTX"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_resolved_via": {
"GM": "security_alias",
"RTX": "security_alias"
},
"include": [
"events"
],
"knowledge_time": "2026-09-18T01:59:25Z",
...
}
}Edge cases
Recycled tickers
GM has had two holders: General Motors Corporation until 2009 and General Motors Company from 2010. Without date, both come back, current holder first (see Request examples). With date, only the holder on that date comes back.
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/GM?date=2005-06-01&include=events"{
"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-01",
"tickers_resolved_via": {
"GM": "security_alias"
},
"include": [
"events"
],
"as_of": "2005-06-01",
...
}
}The same ticker on a date after the handover:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/GM?date=2015-06-01&include=events"{
"data": {
"GM": {
"entities": [
{
"entity_id": 10001879,
"name": "GENERAL MOTORS CO",
"entity_type": "corporation",
"country": "US",
"figi": "BBG000NDYB67",
"cik": "0001467858",
"entity_grain": "security",
"issuer_entity_id": 5,
"share_class": null,
"instrument_type": "common",
"exchange": "NYSE",
"ticker_valid_from": "2010-11-18",
"ticker_valid_to": null
}
]
}
},
"meta": {
"tickers_requested": [
"GM"
],
"tickers_resolved": [
"GM"
],
"tickers_unresolved": [],
"resolved_as_of": "2015-06-01",
"tickers_resolved_via": {
"GM": "security_alias"
},
"include": [
"events"
],
"as_of": "2015-06-01",
...
}
}The 2005 row reports ticker_valid_from as 1968-01-02 rather than the 1962-07-02 of the undated response, because with date the validity dates cover only the continuous period that contains the date.
Share classes
Each share class has its own entity_id and the same issuer_entity_id. A ticker can move between classes of one company: GOOG named Class A until 2014-04-02 and has named Class C since 2014-04-03.
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/GOOGL,GOOG?include=events"{
"data": {
"GOOGL": {
"entities": [
{
"entity_id": 10030636,
"name": "ALPHABET INC",
"entity_type": "corporation",
"country": "US",
"figi": "BBG009S3NB30",
"cik": "0001652044",
"entity_grain": "security",
"issuer_entity_id": 31223,
"share_class": "A",
"instrument_type": "common",
"exchange": "NASDAQ",
"ticker_valid_from": "2014-04-03",
"ticker_valid_to": null
}
]
},
"GOOG": {
"entities": [
{
"entity_id": 10003590,
"name": "ALPHABET INC",
"entity_type": "corporation",
"country": "US",
"figi": "BBG009S3NB30",
"cik": "0001652044",
"entity_grain": "security",
"issuer_entity_id": 31223,
"share_class": "C",
"instrument_type": "common",
"exchange": "NASDAQ",
"ticker_valid_from": "2014-04-03",
"ticker_valid_to": null
},
{
"entity_id": 10030636,
"name": "ALPHABET INC",
"entity_type": "corporation",
"country": "US",
"figi": "BBG009S3NB30",
"cik": "0001652044",
"entity_grain": "security",
"issuer_entity_id": 31223,
"share_class": "A",
"instrument_type": "common",
"exchange": "NASDAQ",
"ticker_valid_from": "2004-08-19",
"ticker_valid_to": "2014-04-02"
}
]
}
},
"meta": {
"tickers_requested": [
"GOOGL",
"GOOG"
],
"tickers_resolved": [
"GOOGL",
"GOOG"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_resolved_via": {
"GOOGL": "security_alias",
"GOOG": "security_alias"
},
"include": [
"events"
],
...
}
}Ambiguous tickers
A bare root that names two listed classes, such as BRK, returns 409 with the candidates (see Errors). Request BRK-A or BRK-B instead, or pass a candidate's entity_id to the data endpoints. In a multi-ticker request the ambiguous ticker moves to meta.tickers_ambiguous and the other tickers resolve:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/BRK,AAPL?include=events"{
"data": {
"AAPL": {
"entities": [
...
]
}
},
"meta": {
"tickers_requested": [
"BRK",
"AAPL"
],
"tickers_resolved": [
"AAPL"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_resolved_via": {
"AAPL": "security_alias"
},
"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
}
]
},
"ambiguous_hint": "pass entity_id=",
...
}
}Delisted companies
A ticker whose company no longer lists a share class returns its past holders, and meta names the company in tickers_no_listed_security. Hess Corporation's last day under HES was 2025-07-17:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/HES?include=events"{
"data": {
"HES": {
"entities": [
{
"entity_id": 10013735,
"name": "HESS CORP",
"entity_type": "corporation",
"country": "US",
"figi": "BBG000BBD070",
"cik": "0000004447",
"entity_grain": "security",
"issuer_entity_id": 315,
"share_class": null,
"instrument_type": "common",
"exchange": "NYSE",
"ticker_valid_from": "1962-07-02",
"ticker_valid_to": "2025-07-17",
...
},
{
"entity_id": 10016793,
"name": "HESSTON CORP",
"entity_type": "corporation",
"country": "US",
"figi": null,
"cik": null,
"entity_grain": "security",
"issuer_entity_id": null,
"share_class": null,
"instrument_type": "common",
"exchange": "NYSE",
"ticker_valid_from": "1973-08-08",
"ticker_valid_to": "1987-05-19"
}
]
}
},
"meta": {
"tickers_requested": [
"HES"
],
"tickers_resolved": [
"HES"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_no_listed_security": {
"HES": {
"issuer_entity_id": 315,
"name": "HESS CORP"
}
},
"tickers_past_holders_only": [
"HES"
],
"include": [
"events"
],
...
}
}With a date after the last listing, HES returns 404 naming the company's entity_id (see Errors).
Dates after the last holder
A dated request after a ticker's last listing returns one of two answers. Where the company is still recorded under the ticker on that date, the response is 404 naming the company's entity_id, as for HES above. Where nothing is recorded under the ticker on that date, the answer is the ticker's last holder before the date: tickers_resolved_via reads last_holder, and the validity dates are null:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/CTLT?date=2025-06-02&include=events"{
"data": {
"CTLT": {
"entities": [
{
"entity_id": 10003787,
"name": "CATALENT INC",
"entity_type": "corporation",
"country": "US",
"figi": "BBG00D0MX6Z4",
"cik": "0001596783",
"entity_grain": "security",
"issuer_entity_id": 12778,
"share_class": null,
"instrument_type": "common",
"exchange": null,
"ticker_valid_from": null,
"ticker_valid_to": null
}
]
}
},
"meta": {
"tickers_requested": [
"CTLT"
],
"tickers_resolved": [
"CTLT"
],
"tickers_unresolved": [],
"resolved_as_of": "2025-06-02",
"tickers_resolved_via": {
"CTLT": "last_holder"
},
"include": [
"events"
],
"as_of": "2025-06-02",
...
}
}Warrants, units and other classes
A symbol shaped like a warrant, unit, right or preferred (OXY-WT) never resolves to the common stock, and a class-suffixed symbol (PBR-A) never resolves to a different class. Both land in tickers_unresolved. In the same request, LBTYA resolves through security_alias_censored:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/LBTYA,LBTYK,VOO,OXY-WT,PBR-A?include=events"{
"data": {
"LBTYA": {
"entities": [
{
"entity_id": 10030548,
"name": "LIBERTY GLOBAL LTD",
"entity_type": "corporation",
"country": "US",
"figi": "BBG01K9HZH92",
"cik": "0001570585",
"entity_grain": "security",
"issuer_entity_id": 31257,
"share_class": "A",
"instrument_type": "common",
"exchange": "NASDAQ",
"ticker_valid_from": "2004-06-08",
"ticker_valid_to": null
},
...
]
},
...
},
"meta": {
"tickers_requested": [
"LBTYA",
"LBTYK",
"VOO",
"OXY-WT",
"PBR-A"
],
"tickers_resolved": [
"LBTYA",
"LBTYK",
"VOO"
],
"tickers_unresolved": [
"OXY-WT",
"PBR-A"
],
"resolved_as_of": "2026-09-27",
"tickers_resolved_via": {
"LBTYA": "security_alias_censored",
"LBTYK": "security_alias_censored",
"VOO": "security_alias_censored"
},
...
}
}Issuer rows
Where only the company, and none of its share classes, carried a ticker, the row has entity_grain: "issuer", entity_id equal to issuer_entity_id, and null instrument_type and exchange. Pass that id to Fundamentals:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/CTAM?include=events"{
"data": {
"CTAM": {
"entities": [
{
"entity_id": 1413,
"name": "CASTLE A M & CO",
"entity_type": "corporation",
"country": "US",
"figi": null,
"cik": "0000018172",
"entity_grain": "issuer",
"issuer_entity_id": 1413,
"share_class": null,
"instrument_type": null,
"exchange": null,
"ticker_valid_from": "1950-01-01",
"ticker_valid_to": "2020-12-31"
}
]
}
},
"meta": {
"tickers_requested": [
"CTAM"
],
"tickers_resolved": [
"CTAM"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_past_holders_only": [
"CTAM"
],
"include": [
"events"
],
...
}
}Predecessors and successors
RTX lists Raytheon Company as a predecessor through the 2020-04-02 merger (see Plan differences above). Resolving Raytheon's own ticker on a date before the merger shows the same link from the other side:
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/RTN?date=2019-06-03&include=events"{
"data": {
"RTN": {
"entities": [
{
"entity_id": 10012171,
"name": "RAYTHEON CO",
"entity_type": "corporation",
"country": "US",
"figi": "BBG0089KLSN8",
"cik": "0001047122",
"entity_grain": "security",
"issuer_entity_id": 6172,
"share_class": "B",
"instrument_type": "common",
"exchange": "NYSE",
"ticker_valid_from": "2001-05-14",
"ticker_valid_to": "2020-04-02",
"succession": {
"predecessors": [],
"successors": [
{
"entity_id": 7749,
"name": "R T X CORP",
"event_type": "merger",
"event_date": "2020-04-02"
}
]
}
}
]
}
},
"meta": {
"tickers_requested": [
"RTN"
],
"resolved_as_of": "2019-06-03",
"tickers_resolved_via": {
"RTN": "security_alias"
},
"include": [
"events"
],
"as_of": "2019-06-03",
...
}
}Link ids are company ids. Pass one to Fundamentals to read the predecessor's own statements, which the RTX ticker does not reach. /v1/fundamentals?entity_id=6172&period_type=annual&start=2017-01-01&fields=revenue returns three annual rows for RAYTHEON CO, the last with period_end 2019-12-31 and revenue 29176 (millions of USD).
Request examples
Resolve GM with a key. The Python client returns the raw JSON as a dict; date_ sends the date parameter. The MCP tool resolve_ticker returns the same body as the curl request.
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")
info = xfl.resolve("GM")
for e in info["data"]["GM"]["entities"]:
print(e["entity_id"], e["name"], e["ticker_valid_from"], e["ticker_valid_to"])
for day in ["2005-06-01", "2015-06-01"]:
info = xfl.resolve("GM", include=["events"], date_=day)
e = info["data"]["GM"]["entities"][0]
print(day, e["entity_id"], e["name"])curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.xfinlink.com/v1/resolve/GM"Which companies have traded under the ticker GM, and what are their xfinlink entity ids?10001879 GENERAL MOTORS CO 2010-11-18 None
10001629 GENERAL MOTORS CORP 1962-07-02 2009-06-01
2005-06-01 10001629 GENERAL MOTORS CORP
2015-06-01 10001879 GENERAL MOTORS CO{
"data": {
"GM": {
"entities": [
{
"entity_id": 10001879,
"name": "GENERAL MOTORS CO",
"entity_type": "corporation",
"country": "US",
"figi": "BBG000NDYB67",
"cik": "0001467858",
"entity_grain": "security",
"issuer_entity_id": 5,
"share_class": null,
"instrument_type": "common",
"exchange": "NYSE",
"ticker_valid_from": "2010-11-18",
"ticker_valid_to": null,
"classifications": {
"sic_code": "3711",
"naics_code": "336110",
"gics_sector": "Consumer Discretionary",
"gics_group": "Automobiles & Components",
"gics_industry": "Automobiles",
"gics_sub_industry": "Automobile Manufacturers",
"classification_as_of": "2026-09-18"
},
"index_membership": [
{
"index": "SP500",
"index_name": "S&P 500",
"added": "2013-06-07",
"removed": null
}
]
},
{
"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": "1962-07-02",
"ticker_valid_to": "2009-06-01",
"classifications": {
"sic_code": "3711",
"naics_code": "336110",
"gics_sector": "Consumer Discretionary",
"gics_group": "Automobiles & Components",
"gics_industry": "Automobiles",
"gics_sub_industry": "Automobile Manufacturers",
"classification_as_of": "2026-09-18"
},
"index_membership": [
{
"index": "SP500",
"index_name": "S&P 500",
"added": "1925-12-31",
"removed": "2009-06-02"
}
]
}
]
}
},
"meta": {
"tickers_requested": [
"GM"
],
"tickers_resolved": [
"GM"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_resolved_via": {
"GM": "security_alias"
},
"include": [
"events",
"index",
"classifications"
],
"entity_id_grain": "per row: entity_grain='security' means entity_id is the share-class id; 'issuer' means no share class carries the ticker and entity_id is the issuer id",
"knowledge_time": "2026-09-26T18:09:11Z",
"freshness": [
{
"dataset": "identifiers",
"through": "2026-07-30",
"promoted_at": "2026-09-18T05:17:40Z"
},
{
"dataset": "entities",
"through": "2026-09-13",
"promoted_at": "2026-09-18T05:14:35Z"
},
{
"dataset": "listings",
"through": "2026-08-25",
"promoted_at": "2026-09-18T05:31:46Z"
},
{
"dataset": "entity_events",
"through": "2026-08-17",
"promoted_at": "2026-09-18T05:18:51Z"
},
{
"dataset": "index_membership",
"through": "2026-09-21",
"promoted_at": "2026-09-26T18:12:42Z"
},
{
"dataset": "classifications",
"through": "2026-09-18",
"promoted_at": "2026-09-18T05:22:46Z"
}
]
}
}{"tool": "resolve_ticker", "arguments": {"ticker": "GM"}}
{
"data": {
"GM": {
"entities": [
{
"entity_id": 10001879,
"name": "GENERAL MOTORS CO",
"entity_type": "corporation",
"country": "US",
"figi": "BBG000NDYB67",
"cik": "0001467858",
"entity_grain": "security",
"issuer_entity_id": 5,
"share_class": null,
"instrument_type": "common",
"exchange": "NYSE",
"ticker_valid_from": "2010-11-18",
"ticker_valid_to": null,
"classifications": {
"sic_code": "3711",
"naics_code": "336110",
"gics_sector": "Consumer Discretionary",
"gics_group": "Automobiles & Components",
"gics_industry": "Automobiles",
"gics_sub_industry": "Automobile Manufacturers",
"classification_as_of": "2026-09-18"
},
"index_membership": [
{
"index": "SP500",
"index_name": "S&P 500",
"added": "2013-06-07",
"removed": null
}
]
},
{
"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": "1962-07-02",
"ticker_valid_to": "2009-06-01",
"classifications": {
"sic_code": "3711",
"naics_code": "336110",
"gics_sector": "Consumer Discretionary",
"gics_group": "Automobiles & Components",
"gics_industry": "Automobiles",
"gics_sub_industry": "Automobile Manufacturers",
"classification_as_of": "2026-09-18"
},
"index_membership": [
{
"index": "SP500",
"index_name": "S&P 500",
"added": "1925-12-31",
"removed": "2009-06-02"
}
]
}
]
}
},
"meta": {
"tickers_requested": [
"GM"
],
"tickers_resolved": [
"GM"
],
"tickers_unresolved": [],
"resolved_as_of": "2026-09-27",
"tickers_resolved_via": {
"GM": "security_alias"
},
"include": [
"events",
"index",
"classifications"
],
"entity_id_grain": "per row: entity_grain='security' means entity_id is the share-class id; 'issuer' means no share class carries the ticker and entity_id is the issuer id",
"knowledge_time": "2026-09-26T18:09:11Z",
"freshness": [
{
"dataset": "identifiers",
"through": "2026-07-30",
"promoted_at": "2026-09-18T05:17:40Z"
},
{
"dataset": "entities",
"through": "2026-09-13",
"promoted_at": "2026-09-18T05:14:35Z"
},
{
"dataset": "listings",
"through": "2026-08-25",
"promoted_at": "2026-09-18T05:31:46Z"
},
{
"dataset": "entity_events",
"through": "2026-08-17",
"promoted_at": "2026-09-18T05:18:51Z"
},
{
"dataset": "index_membership",
"through": "2026-09-21",
"promoted_at": "2026-09-26T18:12:42Z"
},
{
"dataset": "classifications",
"through": "2026-09-18",
"promoted_at": "2026-09-18T05:22:46Z"
}
]
}
}Was this page helpful?
Thank you for helping improve xfinlink documentation.
- Need help? Get in touch.
- Building with an LLM? Read llms.txt.
- Using Claude or ChatGPT? Connect the MCP server.