# Get securities and listings Available securities and listing venues for a company, fund or share class, with their identifiers. ## How it works {#how-it-works} - **One entry per security.** Each entry has an ISIN. A share class can have identifiers and an empty `venues` list when no exchange listing is established. - **`is_primary` marks a supported primary listing.** It is null when the primary is unknown. A venue can reflect a documented admission. Its currency is null when the trading currency of that line is unknown. - **Primary lines appear first.** Within each priority, venues are grouped by operating market. Lines with a ticker precede tickerless admissions on the same market. Each segment retains its own MIC. - **Currencies are ISO 4217 codes, never minor units.** A London line quoted in pence has `currency` GBP, Johannesburg cents are ZAR and Tel Aviv agorot ILS. - **Ticker formats depend on the source.** The reported ticker can use a different format from the symbol shown by the exchange. - **Every venue can be looked up again.** Send its `ticker` and `mic` (or `operating_mic`) back as `ticker:mic`, such as `APC:XBER` for Apple in Berlin, to get the same security. - **If we can't tell which company you mean, you get a 404 saying so.** Add the exchange to the ticker, or use an ISIN: `TSCO:LN` rather than `TSCO`. ## Request {#request} `GET /api/v1/listings` with your API key. AI assistants call it as the `get_listings` tool, with the same parameters. ``` curl "https://financialdb.ai/api/v1/listings?q=AAPL:US" \ -H "Authorization: Bearer $FDB_API_KEY" ``` ## Parameters {#parameters} | Parameter | Type | Description | |---|---|---| | `include_sources` | boolean | Include available source documents and supporting evidence. Omit for data only. Default: `false`. | | `q` (required) | string | Ticker with its exchange code or MIC (AAPL:US, AAPL:XNAS, TSCO:XLON), ISIN, CUSIP, SEDOL, WKN, FIGI, LEI, CIK or company registration number. Any ticker and mic a listing returns work as ticker:mic. | ## Response {#response} JSON with these fields. A field the source doesn't report is null or left out. When nothing matches, `message` says why and what to ask instead. Empty answers are free. | Field | Description | |---|---| | `query` | The identifier asked for | | `identifier_type` | Type of the submitted identifier, null when ambiguous | | `listings[].isin` | ISIN of the security | | `listings[].cusip` | Reported CUSIP for this ISIN; null when conflicting | | `listings[].sedol` | Reported SEDOL for this ISIN; null when conflicting | | `listings[].wkn` | Reported WKN for this ISIN; null when conflicting | | `listings[].share_class_figi` | Reported share-class FIGI for this ISIN; null when conflicting | | `listings[].venues[].ticker` | Reported ticker for this trading line, which may use the source's symbol format | | `listings[].venues[].exchange` | Exchange name | | `listings[].venues[].mic` | Most specific ISO 10383 MIC of the trading line: a segment MIC (XNGS) or, off-segment, the operating MIC | | `listings[].venues[].operating_mic` | ISO 10383 MIC of the exchange that runs the segment (XNAS for XNGS); equal to mic on the operating market itself | | `listings[].venues[].country` | ISO 3166-1 alpha-2 country code of the exchange | | `listings[].venues[].currency` | ISO 4217 currency of this listing, never a minor unit: a London line quoted in pence is GBP. Null when unavailable or conflicting | | `listings[].venues[].figi` | FIGI of this trading line (venue level) | | `listings[].venues[].composite_figi` | Country-level composite FIGI of this listing | | `listings[].venues[].listed_on` | Reported listing date at this exchange, not necessarily the company's IPO date | | `listings[].venues[].is_primary` | Whether it's the primary listing; null when the primary is unknown | | `match` | Identifier lookup outcome. A found match can still have an empty page. | | `message` | Only when there are no listings: why, and what to ask instead | ## Errors {#errors} | Status | Meaning | |---|---| | 400 | Missing, unknown or invalid parameter, or an identifier that can't be looked up | | 401 | Missing, unknown or revoked API key | | 402 | No active plan or trial, or the included request allowance is used | | 403 | API access of the account is suspended | | 404 | The identifier matches nothing or is ambiguous. The match field identifies the outcome | | 429 | Over the plan's rate limit; Retry-After says when to retry | | 500 | Internal error; the same request is unlikely to succeed on retry | | 503 | The data couldn't be loaded right now; Retry-After says when to retry, when known | Errors are JSON with an `error` message saying what to fix. Errors are free. See [Errors and limits](https://financialdb.ai/documentation/api/errors-and-limits.md).