Companies & stocks

Dataflow distinguishes between the legal entity and its tradable instruments.

Companies

A company is the listed legal entity: Volvo AB, not VOLV B. Ownership, free float, short interest and buybacks are tracked at company level. Companies carry a company_id, an LEI where one exists, a country, sector/industry classification and their market listings.

Two things to know about company_id:

• It's Modular Finance's internal identifier and the join key across every domain and both interfaces; REST and MCP use the same IDs.
• The numbers carry no meaning. Negative IDs are normal and are not a flag for unlisted, private or anything else. Pass them through verbatim.

Stocks (share classes)

A stock is one share class of a company: Volvo AB has VOLV A and VOLV B. Stocks carry a stock_id, ISIN, ticker symbol, listing currency and market segments. Companies with multi-class structures have several stocks with different voting power, which is why a position's capital fraction and votes fraction can differ. See Changes & deltas for how both are reported.

Which denominator?

Capital and votes fractions are computed on the company's total issued share capital, the usual convention in the Nordics. The alternative is the treasury-adjusted basis: shares outstanding, excluding shares the company holds itself, which is the usual convention in the UK.

• MCP: the ownership and short-interest tools take an adjust_treasury boolean, so a single session can read a UK company on the UK convention and a Nordic one on the Nordic convention. Omit it and your organisation's configured basis applies (unadjusted unless configured otherwise); every response echoes the treasury_adjusted basis it was computed on.
• Feeds that cannot adjust: list_market_transactions, get_lockups, list_block_trades, list_buyback_transactions and get_free_float always report fractions of total issued capital. They take no adjust_treasury, and their tool descriptions say so.
• Reconciling: get_shares_outstanding reports both share counts regardless of configuration, so you can always recover the denominator behind a fraction.

Money and currency

Values that Dataflow computes rather than observes - a position's market value, the value of an ownership change, a short position's value, an insider's holding value - are reported in the currency that company's shares trade in. A position in a UK company is a GBP figure, one in a Swedish company a SEK figure; that is the currency the number is actually denominated in, and no conversion sits between you and it.

Amounts that are contractual rather than computed keep the currency they were declared in for the same reason: a share price, a dividend amount, a buyback authorisation, a lock-up value. Either way every figure travels with the currency it is reported in - always read the currency field beside the number, because one response can legitimately mix several.

Pass the optional currency argument (any ISO 4217 code, e.g. "GBP") to convert a response instead. Use it when you are comparing or adding up companies from different markets, which is the only case where a single currency is needed. A tool that accepts it converts every computed money field in its response, and the currency fields then name the code you asked for.

Some figures span several markets and so have no trading currency of their own. They are reported in USD unless you pass currency:

• portfolio_value on get_owner_portfolio, the total the per-position portfolio_weight fractions are computed against. portfolio_value_currency names it.
• the min_delta_value threshold on list_market_transactions, echoed back as min_delta_value_currency. The rows of that feed are never converted - each reports the change in its own company's trading currency.
• the min_value threshold on list_market_block_trades, echoed back as min_value_currency. Its rows are not converted either - each print is priced in the currency its own stock trades in.
• mcap on list_companies, together with the min_mcap / max_mcap bounds it is filtered on, echoed back as mcap_currency. This is the one place rows are converted by default: a screener puts companies from different markets in a single ranked list, and in mixed currencies neither the ordering nor the bounds would mean anything.

cost_basis on holdings and portfolio positions is the owner's average acquisition cost per share (GAV), reported in the currency that share class trades in so it compares directly against a share price. Where an owner holds more than one share class, the position's figure is the share-weighted blend of the classes, and the per-class figures are in the stock breakdown.

Looking things up

• REST: the /entities/company and /entities/stock endpoints serve reference data, filterable by country, symbol or company-ids.
• MCP: search_securities resolves free text (a name, ticker, ISIN or LEI) to companies with their share classes. When you have no name to resolve, list_companies goes the other way and returns every company matching a sector, industry, country, market segment or market-cap range, largest first. Both report each company's sector, industry and primary listing; the ids those filters take come from list_sectors and list_market_segments, and are worth reading rather than guessing - the sector taxonomy is Modular Finance's own, not GICS or ICB.

Note that a company's country is where it is incorporated, while its market segment's country is where it trades. They differ often enough to matter: Man Group is a FTSE 100 constituent incorporated in Jersey. The countries filter on both tools selects on the listing, so a UK screen finds it.