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

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).

What changed — technical walkthrough

1. Endpoint paths

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):

// 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:

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

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:

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

5. New fields

Company-level (list and profile):

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.

"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:

curl "https://api.fiscal.ai/v3/company/profile?fscl=FSCLC6CGT4DXS597&apiKey=YOUR_API_KEY"

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.

"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. 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) always report an empty array.

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 are venue-accurate — each listing carries the FIGI of that specific exchange line.
• 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.