> Fiscal.ai API docs. Source: https://docs.fiscal.ai/docs/migrations/companies-list-v2-to-v3. Every page is listed in https://docs.fiscal.ai/llms.txt; append `.md` to any docs URL for its Markdown.

# Fiscal.ai API - Companies List & Profile, v2 → v3

How to migrate the Companies List and Company Profile endpoints from v2 to v3 — why coverage expanded from ~12,000 to ~55,000 companies with secondary listings, and every field, rename, and behavior change you need to make the switch.

*How to move from the v2 Companies List and Company Profile endpoints to v3. This guide covers only those two endpoints.*

## Why we built v3

The v2 company list was built around a single primary listing per company, mostly in the US. That model couldn't represent how companies actually trade in the world, and it capped how much we could tell you about each one.

v3 rebuilds the list to fix both:

- **Far more companies.** Coverage grows from roughly **12,000** companies to about **55,000** — spanning 20+ countries.
- **Secondary listings included.** A company that trades on several exchanges is now returned with its full set of listings, not just one line. You can see every place a company trades and pick the venue that matters to you.
- **Far more metadata per company.** Every company now carries stable identifiers, legal and trade names (including native-language names), company type and status, headquarters region and legal domicile, latest market cap in USD, and its peer set — none of which existed in v2.

Delivering this meant changing the shape of the response. A company can no longer be described by one flat row of ticker/exchange fields, so those fields now live inside a listing object, and several fields were renamed and added. **These are breaking changes** — v2 responses will not parse against v3, and vice versa. The rest of this guide is the exact, field-by-field mapping your engineers need to make the switch.

v2 keeps working with its existing shape and fields, so you can migrate on your own schedule — but it is frozen: it will not receive the expanded coverage, the new fields, or the new datasets. v2 is now served from the same rebuilt company list as v3, so the data-quality improvements described in step 11 (names, countries, classifications) also show up in v2 values — including `exchangeSymbol`, which now carries the same values as v3's `exchangeCode` (international venues report the ISO operating MIC, see step 2).

> **The two endpoints:** [Companies List (v3)](https://docs.fiscal.ai/docs/api-reference#companies-list) and [Company Profile (v3)](https://docs.fiscal.ai/docs/api-reference#company-profile) are live. The v2 versions still work but are deprecated and frozen. For the full guide to everything v3 offers, see [Companies List & Profile](https://docs.fiscal.ai/docs/guides/companies-list).

## What changed — technical walkthrough

### 1. Endpoint paths

| v2 | v3 |
| --- | --- |
| `GET /v2/companies-list` | `GET /v3/companies-list` |
| `GET /v2/company/profile` | `GET /v3/company/profile` |

### 2. Listing fields moved into `primaryListing`

In v2 the primary exchange line was a set of flat top-level fields. In v3 those fields move into a nested **`primaryListing`** object (present on both the list row and the profile):

```json
// v2 (flat)
{ "ticker": "MSFT", "exchangeSymbol": "NASDAQ", "exchangeName": "Nasdaq", "micCode": "XNAS", "figi": "BBG000BPHFS9" }

// v3 (nested)
{ "primaryListing": { "ticker": "MSFT", "exchangeCode": "NASDAQ", "exchangeName": "Nasdaq Stock Market", "operatingMic": "XNAS", "figi": "BBG000BPHFS9" } }
```

Mapping of the moved fields:

| v2 (top-level) | v3 (`primaryListing.*`) | Note |
| --- | --- | --- |
| `ticker` | `ticker` | |
| `exchangeSymbol` | `exchangeCode` | Renamed, and values change outside North America: US/Canadian venues keep their familiar codes (`NASDAQ`, `NYSE`, `TSX`, …), while international venues now use the ISO operating MIC (Stockholm: `OM` → `XSTO`). |
| `exchangeName` | `exchangeName` | Value is now the full exchange name (`Nasdaq` → `Nasdaq Stock Market`). |
| `micCode` | `operatingMic` | |
| `tradingCurrency` | `tradingCurrency` | |
| `tradingStatus` | `tradingStatus` | Value vocabulary changed — see step 4. |
| `figi` | `figi` | Semantics differ: v2 serves the composite (country-level) FIGI, matching the pre-v3 list; v3 listings carry venue-level FIGIs (see the FIGI note below). Both forms are accepted for lookups. |
| `cusip` (license-gated) | `cusip` (license-gated) | Present only with a CUSIP/ISIN license. |
| `isin` (license-gated) | `isin` (license-gated) | Present only with a CUSIP/ISIN license. |

`primaryListing` also adds fields that did not exist in v2: `listingFiscalIdentifier`, `exchangeCountryCode`, `exchangeCountryName`, `segmentMic`, `segmentName`, `securityType`, and `securityFiscalIdentifier`. On the profile, every `secondaryListings` entry carries the same shape.

`securityType` is one of: `common_stock`, `preferred_stock`, `depositary_receipt`, `unit`.

### 3. Renamed top-level fields

| v2 | v3 |
| --- | --- |
| `name` | `displayNameEnglish` |
| `countryCode` | `headquartersCountryCode` |
| `countryName` | `headquartersCountryName` |
| `description` (profile only) | `descriptionLong` (profile only) |
| `shortDescription` (profile only) | `descriptionShort` (profile only) |

Unchanged names (still top-level, same key): `companyId`, `companyKey`, `sector`, `industryGroup`, `industry`, `subIndustry`, `reportingTemplate`, `cik`, `reportingCurrency`, `updatedAt`, `earningsFilingDate`, and `availableDatasets`.

### 4. `tradingStatus` values changed; `isPreIpo` removed

`tradingStatus` (now under `primaryListing`) moved from a two-state label to a raw enum:

| v2 | v3 |
| --- | --- |
| `Active` | `active` |
| `Inactive` | `delisted`, `suspended`, `pre_ipo` |

The separate v2 `isPreIpo` boolean is **removed**. Check `primaryListing.tradingStatus === "pre_ipo"` instead.

### 5. New fields

**Company-level (list and profile):**

| Field | Notes |
| --- | --- |
| `companyFiscalIdentifier` | Fiscal.ai's stable company identifier (`FSCLC…`) — a durable join key, and a lookup parameter (step 8). |
| `marketCapUsd` | Latest market capitalization in USD, computed from shares outstanding and share prices (number, or `null` when it cannot be computed reliably). |
| `legalNameEnglish` / `tradeNameEnglish` | Legal and trade names in English. |
| `legalNameNative` / `tradeNameNative` | Same, in the native language/script (may be empty). |
| `companyType` | `operating_company`, `investment_company`, `reit`, `spac`, `government`. |
| `companyStatus` | `active`, `defunct`, `dormant`, `reorganizing`, `shell`. |
| `headquartersRegion` | e.g. `North America`. |
| `legalDomicileCountryCode` / `legalDomicileCountryName` | Legal domicile (distinct from headquarters). |

**Profile only, additionally:** `chiefExecutiveOfficer`, `foundingYear`, `ipoYear`, plus `secondaryListings` and `peers` (step 6). Note there was **no `ceo` field in v2** — `chiefExecutiveOfficer` is new.

### 6. Profile: `primaryListing`, `secondaryListings`, and embedded `peers`

The v2 profile returned only the primary listing's fields (flat) and had no listings array and no peers. The v3 profile splits and enriches this:

- **`primaryListing`** — the primary exchange line (same object shape as the list row). `null` only when no primary listing is on file.
- **`secondaryListings`** — an array of every other listing the company trades under, each with the same full listing shape. This is the core of the coverage expansion.
- **`peers`** — the company's peer set, embedded directly in the profile. Each entry carries the relationship metadata (`peerRelationship`, `peerMarketSegment`, `peerReasoning`) plus a reduced company summary and a minimal `primaryListing`.

`peerRelationship` is one of: `direct_competitor`, `business_model_peer`, `industry_peer`.

```json
"peers": [
  {
    "peerRelationship": "direct_competitor",
    "peerMarketSegment": null,
    "peerReasoning": "Alphabet is a direct competitor across cloud (Google Cloud vs. Azure), productivity software, search, and AI.",
    "companyId": 5,
    "companyFiscalIdentifier": "FSCLC9GRT8AJP994",
    "companyKey": "NASDAQ_GOOG",
    "displayNameEnglish": "Alphabet Inc.",
    "companyType": "operating_company",
    "headquartersCountryCode": "US",
    "headquartersCountryName": "United States",
    "headquartersRegion": "North America",
    "sector": "Communication Services",
    "industryGroup": "Media & Entertainment",
    "industry": "Interactive Media & Services",
    "subIndustry": "Interactive Media & Services",
    "marketCapUsd": 4280950000000,
    "cik": "1652044",
    "primaryListing": {
      "listingFiscalIdentifier": "FSCLL3SZG8XUR640",
      "ticker": "GOOG",
      "exchangeCode": "NASDAQ",
      "exchangeName": "Nasdaq Stock Market",
      "operatingMic": "XNAS",
      "securityFiscalIdentifier": "FSCLS7JJK7ZZY623",
      "isin": "US02079K1079",
      "cusip": "02079K107",
      "figi": "BBG009S4MVF2"
    }
  }
]
```

### 7. Compact list (`compact=true`)

`GET /v3/companies-list?compact=true` returns a slimmer row. Compared to the full row it drops the company-level fields `tradeNameEnglish`, `legalNameNative`, `tradeNameNative`, `legalDomicileCountryCode`, `legalDomicileCountryName`, `industryGroup`, `industry`, and `subIndustry`; and its `primaryListing` drops `exchangeCountryCode`, `exchangeCountryName`, `segmentMic`, and `segmentName`. All identifiers, `marketCapUsd`, and `availableDatasets` are retained. Default is the full shape.

### 8. Look up a single company by `fscl`

Every single-company endpoint accepts a new lookup parameter, **`fscl`** — the short URL form of `companyFiscalIdentifier` (the value is the same `FSCLC…` string). It sits alongside `companyKey`, ticker + exchange, ticker + MIC code, CUSIP, ISIN, FIGI, CIK, and (US listings) bare ticker:

```bash
curl -H "X-Api-Key: $FISCAL_API_KEY" "https://api.fiscal.ai/v3/company/profile?fscl=FSCLC6CGT4DXS597"
```

The response field is still named `companyFiscalIdentifier`; only the query parameter is shortened to `fscl`. Because it is stable across ticker changes, exchange moves, and re-listings, it is the recommended durable key.

### 9. Pagination & company set (Companies List)

Pagination keeps the same envelope (`page`, `pageSize`, `totalPages`, `totalCount`, `hasNextPage`, `hasPreviousPage`) and pages remain 1-indexed with `pageNumber` defaulting to `1`. Two things change:

- **No `pageSize` parameter.** Page size is fixed at 1000 rows (v2 accepted a `pageSize` of up to 1000). The final page contains the remainder — size it by `data.length`.
- **Counts follow the company set.** `totalCount` and `totalPages` reflect the selected set (see below). Page until `hasNextPage` is `false`.

```json
"pagination": { "page": 1, "pageSize": 1000, "totalPages": 12, "totalCount": 11946, "hasNextPage": true, "hasPreviousPage": false }
```

**Company set.** By default the list returns **only companies with API-enabled data** — the set you can actually pull financials for (~12,000). Pass `allCompanies=true` to page through the entire ~55,000-company universe instead; `totalCount` and `totalPages` adjust to the selected set.

### 10. `availableDatasets`

`availableDatasets` keeps its name but its vocabulary changed. It lists the datasets you can pull for the company, drawn from: `filings`, `financials`, `adjusted_numbers`, `stock_prices`, `ownership`, `news`, `logos`, `segments_and_kpis`, `events_calendar`, `investor_relations`, `fund_letters`, `estimates`. The vocabulary grows as new datasets launch, so treat unrecognized values as informational rather than errors. Companies outside the API-enabled set (returned with `allCompanies=true`) report an empty array, except that `segments_and_kpis` and `fund_letters` are listed when covered — their endpoints serve companies not yet API-enabled, so their availability is advertised too.

### 11. Expect some values to improve, not just move

v3 re-researched the underlying company data rather than copying v2's values, so beyond the renames above, some field **values** will differ for the same company:

- **Names** are cleaned up and standardized (e.g. `Husqvarna Ab` → `Husqvarna AB`), and native-language names were added.
- **Country fields** are corrected: v2's single country occasionally reflected the country of incorporation instead of the headquarters. v3 reports both explicitly (`headquartersCountry*` vs `legalDomicileCountry*`), so offshore-incorporated companies may show a different headquarters country than they did in v2.
- **GICS classifications** (`sector` → `subIndustry`) were re-verified and corrected where wrong.
- **FIGIs** come in three granularities on every listing: `figi` is venue-accurate (the FIGI of that specific exchange line), `figiComposite` is the country-level composite, and `figiShareClass` is the global share class. The value you stored from v2's `figi` field is v3's `figiComposite`. All three forms are accepted as `figi=` lookup inputs.
- **`tradingCurrency` reports the exchange's order-book unit** — e.g. London pence lines return `GBX` (v2 collapsed these to `GBP`), so the currency label always matches the unit the listing's prices are quoted in.

If any of your internal logic keys on v2 field values (names, countries, GICS), plan a one-time reconciliation pass joining on `companyFiscalIdentifier` (or `companyId`) rather than string matching.

## Migration checklist

- [ ] Point requests at `/v3/companies-list` and `/v3/company/profile`.
- [ ] Read the primary listing fields from `primaryListing.*` (moved from top level): `ticker`, `exchangeCode` (was `exchangeSymbol` — non-US/CA values are now operating MICs, see step 2), `exchangeName`, `operatingMic` (was `micCode`), `tradingCurrency`, `tradingStatus`, `figi`, `cusip`, `isin`.
- [ ] Apply the top-level renames: `name → displayNameEnglish`, `countryCode → headquartersCountryCode`, `countryName → headquartersCountryName`, and on the profile `description → descriptionLong`, `shortDescription → descriptionShort`.
- [ ] Replace `tradingStatus === "Active"` with `primaryListing.tradingStatus === "active"`; drop `isPreIpo` and use `primaryListing.tradingStatus === "pre_ipo"`.
- [ ] On the profile, read all listings from `primaryListing` + `secondaryListings` (v2 had neither), and the company's peer set from `profile.peers`.
- [ ] Adopt `companyFiscalIdentifier` as your stable join key, and optionally use `fscl=<id>` as a lookup parameter.
- [ ] Update pagination: there is no `pageSize` param (fixed 1000 rows per page); the envelope and 1-indexed `pageNumber` are unchanged.
- [ ] Decide your company set: the default is API-enabled companies only — pass `allCompanies=true` for the full ~55,000 universe.
- [ ] Optionally request `compact=true` when you don't need the full descriptor set.
- [ ] If you consume `availableDatasets`, adopt the new vocabulary.
- [ ] Pick up the new metadata where useful: `marketCapUsd`, legal/trade names, `companyType`/`companyStatus`, `headquartersRegion`, legal domicile, and (profile) `chiefExecutiveOfficer`/`foundingYear`/`ipoYear`.
