Fundamentals

What's inside#

Prices and bars, including /api/v3/fundamentals/price_snapshot and /api/v3/fundamentals/prices, are documented on Market Data. SEC filing lists are on Public Filings, and insider trades and institutional ownership are on Funds & Institutional.

Access#

Most routes on this page are the fundamentals product: included on Free and every paid tier (Starter, Pro, Expert, Enterprise), and each call debits 1 credit. Several routes under /api/v3/fundamentals/ bill as a different product:

Each row in the tables below states its plan and credit cost. Failed requests are not billed.

Endpoints#

Company snapshots, profiles and search#

company_facts has two shapes. Usually facts holds ticker, name, cik, exchange (a market identifier code such as XNAS), sector (the SIC division, such as Manufacturing), industry (the SIC description), sic_code, sic_description, list_date, market_cap, description, homepage_url, address, is_active, currency_name, locale and market. It carries no employee count, officers, S&P 500 flag or financial figures. When that source has no record for the symbol, for example BRK-B (hyphenated share class) or a delisted ticker, a fallback profile is served instead. The fallback uses a different sector and industry taxonomy, names the website website and the SIC code sic, has no market_cap, and adds ipo_date, is_sp500, full_time_employees, officers, fiscal_year_end, former_names and the latest annual, quarterly and TTM figures. Check which keys are present before reading them. For employees, officers and financial figures on any ticker, use company_full/{ticker}.

Financial statements and history#

eps_repair on income statements. A quarterly EPS derived as the fiscal year minus the other quarters can straddle a stock split and come out with the wrong sign. When a row's EPS contradicts its own net income, income_statements looks the period up in a second source. If that source reports the same net income and an EPS with the same sign, its EPS is served; otherwise the EPS field is null. The row then carries eps_repair with reason (eps_sign_contradicts_net_income), vendor_values (what the first source said), fields_replaced and fields_withheld. Read a null EPS on such a row as withheld, not as zero.

Fiscal fourth quarters carry their own per-share figures. A 10-K reports the year, not its fourth quarter, so a fiscal-Q4 row is the year less the first three quarters. That is right for revenue and net income and wrong per share: the row used to carry the year's weighted share count under the quarter's label, and an EPS a cent or two away from the company's own release. A fiscal-Q4 row on quarterly income_statements now takes eps_basic, eps_diluted and shares_outstanding (also weighted_average_shares_basic) from the filer's SEC filings, and says how in fiscal_q4_per_share:

• status is reported when the filer tagged a three-month figure for the quarter, which is served as filed, and derived when the quarter's weighted shares were taken out of the year, day-weighted: the year's average times its days, less each of the first three quarters' average times its days, over the quarter's days. EPS is then the quarter's net income over those shares, rounded to the cent. partially_derived means only some of the figures could be derived. withheld (with a reason) and sec_check_unavailable (the SEC read failed; retry shortly) leave the per-share fields null; they are never the year's figures under the quarter's label.
• period (start, end, days), shares_diluted, source (sec_companyfacts) and sec_as_of describe the derivation, and shares_diluted_basis lists the filings it used. Basic weighted shares add up exactly over days. Diluted shares are a close approximation.
• cent_ambiguous lists the EPS fields (eps_basic, eps_diluted) whose cent cannot be decided because the filer rounds its share counts, to millions for example. Microsoft's fiscal Q4 2025 basic EPS derives to 3.67 against a reported 3.66. Treat a listed field as accurate to within a cent.
• vendor_eps_basic, vendor_eps_diluted and vendor_shares_outstanding keep the previous figures wherever the served one differs.

Apple's fiscal Q4 2025 row reads eps_basic 1.85 and eps_diluted 1.85 on 14,815,308,000 shares (status: "derived"), where it read 1.86 and 1.84 on 14,948,500,000. TTM figures sum the corrected quarter: on TTM income_statements, metrics_snapshot, full and company_full, and in eps_ttm, pe_ttm and forward_pe on price_snapshot (Apple's eps_ttm is 8.72, was 8.71).

Growth, dividends and screening#

Earnings releases, news and analysis#

As-reported and point-in-time#

Knowledge dates in the point-in-time archive. as_of answers use S&P's own snapshot dates as knowledge dates, not the dates Wealthnow received each version. The newest weekly snapshot reaches us about two weeks after its snapshot date, so an as_of within the last two weeks can include a version we did not yet hold on that date. The values match S&P's exactly.

Segments#

Periods and units in company snapshots#

metrics_snapshot, company_full and full combine blocks that cover different periods and use different units. A quarter's ROE of 28% and a trailing ROE of 84% can sit side by side, so read each block's period and units before comparing numbers.

period is on every block: type, fiscal_year, fiscal_quarter, start and end.

Cash-flow blocks add period.basis: discrete, year_to_date or unverified.

units names the unit of every numeric field in the block; a null field has no unit. The vocabulary is percent (84.23 is 84.23%), fraction (0.2812 is 28.12%), usd, usd_per_share, multiple, shares, count and days. Money is usd for a US issuer. Otherwise it is reporting_currency (or reporting_currency_per_share) and the block adds currency, the ISO code, or currency: null with currency_status: "not_reported_by_source". field_periods flags a field whose period differs from its block's, for example shares_outstanding as the latest quarter's count inside a TTM block. Cash-flow blocks carry a sign_convention.

For NVDA's fiscal 2027 second quarter, ratios.roe is 0.2812 (28.12% for that quarter, on average equity) and ttm.ttm_ratios.roe_ttm is 84.23 (84.23% over the trailing twelve months).

Trailing twelve months#

A TTM figure is the sum of the four consecutive fiscal quarters ending with the latest one. A missing fourth quarter is derived as the fiscal year minus the first three. ttm_status says what the window is:

In a complete window, a field that some quarters leave empty is summed over the rest and named in ttm_underfilled_fields; treat it as a floor. cash_flow_row_basis gives each quarter's cash-flow basis (discrete, ytd or unknown). ttm_ratios are recomputed from the checked TTM, and are null when the window is not ok.

Per-share figures on today's share basis. TTM EPS sums each quarter's diluted and basic EPS after restating any quarter filed before a later split, and the latest share count is put on today's basis the same way. eps_ttm_basis says how: status (ok, or why EPS is null: incomplete_ttm, period_end_unknown, mixed_basis_in_data, derived_quarter_spans_split, split_basis_unknown, inconsistent_share_counts, cross_check_failed, splits_unavailable or restatement_failed), basis (as_reported, split_adjusted or as_reported_splits_unchecked), split_factors, cross_check_net_income_over_shares and splits_checked. KLAC's TTM EPS is 3.657 after its 10-for-1 split, not the 27.30 that summing the quarters as filed gives. ratios.book_value_per_share is restated the same way, with the original in book_value_per_share_as_filed, and is null when a split leaves its basis unknown.

Debt ratios#

• ratios.debt_to_assets is total debt (short-term plus long-term) over total assets. The source's figure under that name was total liabilities over total assets; it is now liabilities_to_assets. NVDA: debt_to_assets 0.1042, liabilities_to_assets 0.285. When debt_to_assets is null, debt_to_assets_status says why: balance_sheet_unavailable, debt_not_established or vendor_definition_unverified.
• Debt to equity is null with debt_to_equity_status: "debt_components_missing" when the balance sheet lacks a debt component; debt_components_missing lists which (short_term_debt, long_term_debt). long_term_debt_to_equity is withheld the same way when long-term debt is the gap. The same rule applies in ttm.ttm_ratios.

The cash-flow bridge#

cash_flow_ttm and, in full, cash_flow_latest reconcile operating cash flow with net income:

NVDA's second fiscal quarter of 2027: operating cash flow 24.08B against net income 59.7B, with change_in_receivables -22.35B, other_operating_items -16.42B and cash_conversion_pct 40.34.

The full bundle#

• period_pairs pairs the panes that cover the same period: ttm (income_statement_ttm with cash_flow_ttm), latest_quarter (income_statement_latest_quarter with cash_flow_latest) and point_in_time (balance_sheet_latest). Each has the panes, their end and matched, which is true only when both panes end on the same day, have the named period, and the cash-flow pane is on a discrete basis.
• Insider trades and institutional holders need a plan with the funds product (Starter and up); the call still costs 1 fundamentals credit. On Free both panes are null with status plan_required, and a plan_required block names the fields and the plans that unlock them.

Holder rows carry investor, holder, shares, value_usd and report_period, from 13F filings. institutional_holders_freshness gives newest_report_period, expected_report_period, is_stale and quarters_behind. A null pane always has a status and means unknown; [] means none reported.

Dividends#

The dividends block (in the snapshots and each /dividends item) is the fundamentals source's fiscal-year dividend profile, with its fields named for what they are. Its units map describes each:

Use per_share_split_adjusted for any trend: per_share is never restated for later splits, so a split reads as a cut. NVDA's fiscal 2021 dividend is 0.6402 as filed and 0.016 split-adjusted, the same rate it paid through fiscal 2024. per_share_split_adjusted_basis says whether a year was summed from the market-data dividend record by pay date, or scaled from the as-filed figure by the later splits (vendor_per_share_split_scaled); it is null, with the value, when neither is known.

The dividend block gives the current dividend: status, trailing_per_share (regular dividends with an ex-date in the last 365 days, split-adjusted), indicated_annual_per_share (the latest declared regular dividend times payments per year), frequency, special_ttm_per_share, currency, last_regular with its four dates, source (the market-data corporate-actions feed) and as_of. NVDA: trailing 0.52, indicated 1.00. Its statuses are those listed under Dividend status, except implausible, which only price_snapshot sets.

The revenue growth check#

The fundamentals source can compare two different revenue lines across years. TRV's fiscal 2025 revenue growth was served as +1,123%: net investment income in one year against premiums in the next. So any revenue growth beyond ±100%, or a row whose revenue minus cost of revenue misses its gross profit, is checked against the issuer's SEC annual report, on one revenue concept in both years, with the prior year from that report's comparative column. The check applies on the screener, on /growth, and to the growth block of metrics_snapshot, company_full and full.

A row the check did not run on has no growth_status. A checked row adds:

• vendor_revenue_growth_yoy: the source's figure, always kept.
• revenue_growth_basis: the trigger; when settled, concept, unit, fiscal_year, current and prior (each period_start, period_end, value, accession, form, filed), the formula and revenue_growth_yoy (sec and vendor); when not, reason and, where it applies, retryable.
• On /growth and the snapshot growth blocks, on vendor_concept_mismatch: the 3-year and 5-year CAGRs are recomputed on the same concept, or null when SEC cannot compute them (TRV: 157.83 and 81.54 become 9.8 and 8.83), with the source's in vendor_revenue_growth_3y_cagr and vendor_revenue_growth_5y_cagr. The six margin fields, computed on the contradicted revenue, are null and kept in vendor_margins.
• A CAGR whose span crosses a change of revenue concept is null even when the year-over-year figure is confirmed.

While a check is pending, warning says how many figures are still being checked. /growth also returns revenue_growth_checks (counts by status) and growth_statuses (what each status means) whenever a row was checked.

How the screener sizes and sorts#

The fundamentals source applies the ratio filters (roe_min_pct, revenue_growth_min_pct and the rest). Everything else happens on Wealthnow's own data, over the whole matched set, before the page is cut, and the debt-to-equity ceiling and the revenue-growth floor are applied again to the values served:

• Size and liquidity. Each row gains listing_ticker (the active US listing it was sized on), security_class, exchange, price_usd (last exchange close), adv_21d_usd (average daily dollar volume over the last 21 sessions) and market_cap_usd (close times shares outstanding, summed over the issuer's US-listed common share classes).

• Default floors. With no floor parameters the screen returns only common stock with a market cap of at least $300M and at least $1M a day of dollar volume. A row whose market cap or dollar volume is unknown does not clear a non-zero floor. Pass min_market_cap_usd=0 or min_adv_usd=0 to turn a floor off, which also admits rows whose value is unknown. Rows with no active US listing are always left out.

• Security classes. security_class is a comma list of common, adr, preferred, fund, unit, warrant and other. An unknown class returns 400 invalid_security_class listing the allowed ones. market_cap_usd is null for ADRs and non-equity classes, so widen to them with min_market_cap_usd=0.

• Currency. revenue and net_income stay in the issuer's own reporting currency and are not comparable across rows. revenue_usd and net_income_usd are in US dollars when the reporting currency can be established (a US-incorporated registrant, or the issuer's own SEC filings). A non-USD value is converted at the average rate over its fiscal period, for JPY, KRW, CNY, BRL and EUR only; otherwise the field is null, with the reason in the row's notes. reporting_currency, currency_status and fx say how each value was derived.

• Sorting. sort_by defaults to market_cap_usd. It accepts market_cap_usd, adv_21d_usd, price_usd, revenue_usd, net_income_usd, revenue_growth_yoy, net_income_growth_yoy, eps_growth_yoy, roe, roa, gross_margin, operating_margin, net_margin, debt_to_equity, current_ratio, quick_ratio, payout_ratio, dividend_growth_yoy and years_dividend_growth, plus aliases: market_cap and marketcap sort on market_cap_usd, revenue on revenue_usd, net_income on net_income_usd, adv, adv_21d, adv_usd and dollar_volume on adv_21d_usd, price on price_usd, and the short *_growth names on their *_growth_yoy fields. Any other key returns 400 invalid_sort_by listing the allowed ones. Rows without a value sort last in both directions; revenue_growth_yoy sorts on the checked figure, so a growth withheld by the check sorts last. The response echoes the key it sorted on in sort_by and what you sent in sort_by_requested.

• Market cap withheld. market_cap_usd is null when the close has moved more than 3x, either way, from the split-adjusted close on the date of the share count, because the share count can no longer be trusted. Such rows leave a floored screen. Listings trading at least $1M a day that the market-cap floor dropped because their size could not be verified are named in universe.liquid_without_market_cap and in warning.

• Renamed issuers. A row still filed under a symbol its issuer retired in the last 18 months is sized on the current listing (listing_ticker, with a note), and counted in universe.sized_on_former_symbol.

• What was left out. floors echoes the floors applied. total_matched and total_pages count the rows that cleared the floors and the second debt-to-equity and growth filter. Rows that second filter drops are counted in universe.excluded under negative_equity, debt_to_equity_unknown, debt_to_equity_above_max, revenue_growth_unverified, revenue_growth_unknown, revenue_growth_below_min_after_sec_check or revenue_growth_below_min. universe reports the source's match count, whether every matched row was retrieved (candidate_set_complete), exclusions by reason (excluded, with tickers in excluded_examples), and rows_without_sort_value. fundamentals_stale on a row is true when its fiscal period ended more than 18 months ago.

• Where each number comes from. field_sources names the source of every field, and as_of dates them: prices, shares_outstanding, fx_rates_through, size_snapshot_built_at and size_snapshot_age_s.

• Revenue growth. Growth beyond ±100% is checked against the issuer's SEC annual report (see The revenue growth check), and the growth floor is applied again to the checked figure: TRV's served +1,123% becomes +5.18% and leaves a 20% screen. A figure the check withholds as null does not pass a growth floor. The row's revenue is left as the source reported it, and its notes say what was recomputed. universe.revenue_growth_checks counts the checks by status and growth_statuses explains each. A company the source itself excluded on a wrong figure cannot be recovered.

Screener units and refusals#

• Units. Every filter and row field ending in _pct is a percent number; the older names are the same unit. debt_to_equity, current_ratio and quick_ratio are multiples, and years_dividend_growth is in years. Ratios, margins, growth and payout are for each row's latest fiscal year (fiscal_year), not TTM. units maps every row field to its unit.
• filters_applied states each filter as applied, with its unit and basis, for example roe >= 20% (each row's latest fiscal year (fiscal_year), not TTM; net income / average shareholders' equity). A filter sent under an older name ends with a note naming the _pct parameter. Sector, industry and floor lines are included. The filters echo keeps the older names even when you send _pct ones.
• Negative equity. A row whose equity is negative carries equity_negative: true and keeps its negative debt_to_equity (ABBV -20.49). It never passes debt_to_equity_max.

Before sending anything to the source, the screener refuses a filter it cannot read. Each refusal is a 422 with error and error_code set to the code, a detail that starts "NOTHING WAS SCREENED", is_empty_result_set: false, retryable: false and billed: false, and no items. None is billed. The first failing check wins:

Over MCP, the screener refuses an argument it does not declare instead of ignoring it, because an ignored filter returns an unfiltered screen that looks filtered. The result has isError: true, text that starts "NOTHING WAS RUN" and lists the accepted arguments (with a suggestion when one is close), and structuredContent with error: "unknown_argument", unknown_arguments, accepted_arguments and did_you_mean. Nothing is run or billed. Other tools still ignore arguments they do not declare.

The screener refuses rather than serving an unfloored screen. While its size data is still loading on a server it answers 503 with error: "build_timeout" and Retry-After: 10: a warm-up, so retry once after the wait. When the size data or the fundamentals source cannot be read it answers 503 with error: "upstream_unavailable" and error_code screener_size_data_unavailable or screener_vendor_unavailable. None of these is billed, and none carries an items list.

XBRL freshness#

companyfacts/{ticker} and xbrl/{ticker}/{concept} read SEC EDGAR's live companyfacts document for the company. Each server keeps a copy for up to 3 hours, so a new filing can take a few hours to appear, and the answer says when its copy was read:

TSM's last filing (2026-04-16) carried no financial facts, and its newest are from 2025-04-17, so it answers is_stale: true with later_filings_carry_no_financial_facts.

warning: "no_companyfacts" means SEC holds no XBRL facts for the company. When SEC cannot be read and no archived copy exists, the route answers 503 with error: "upstream_unavailable" and error_code: "sec_edgar_unavailable", Retry-After: 60, not billed.

Whose period is it? On xbrl rows, fy and fp are the fiscal year and period of the filing that carried the fact, so a 10-Q repeats the prior year-end balance under its own Q1. period_fy, period_fp (FY, Q1 to Q4, Q2_YTD, Q3_YTD) and period_months (null for a balance) are the fact's own period. AAPL's total assets at 2025-09-27, carried by its first-quarter fiscal 2026 10-Q, have fy 2026 and fp Q1 but period_fy 2025 and period_fp FY. field_notes explains the five fields.

Point-in-time financials#

The ordinary statement routes serve today's view of every figure, including later restatements. A backtest built on them trades on numbers nobody had at the time. The point-in-time routes keep every version of each fiscal quarter as it was published, stamped with the day that version became public.

• The as-of rule. For each fiscal period, pit/{ticker}?as_of= returns the latest version whose knowledge_date is on or before as_of. Versions published later are excluded by construction.
• Each period carries datadate, fiscal_year, fiscal_quarter, fiscal_year_end_month, currency, knowledge_date, vintage_valid_until, is_current_vintage, earnings_report_date, and a financials block.
• The vintage block on each period says whether this was the first report (is_first_report), how many versions exist (vintages_held_for_period), whether it has been restated since (restated_since_as_of), and, when it has, restated_fields and the current_values of those fields. A figure that was first reported after as_of is listed in fields_first_reported_after_as_of, not counted as a restatement.
• financials holds revenue, sales, net_income, income_before_extraordinary_items, basic and diluted EPS including and excluding extraordinary items, total_assets, total_liabilities, common_equity, stockholders_equity, total_equity, shares_outstanding, and the share counts used for basic and diluted EPS.
• Units. Financial items are in millions of the filing's own reporting currency, carried per period in currency. The archive covers North American filers, so the currency is USD or CAD; do not assume USD. Share counts are in millions of shares. Every response includes a units map.
• What counts as a restatement. Only a value that changed. Re-publishing identical numbers is not a restatement, and the response states this in restatement_definition. A first-version value that differs from the current one by a power of ten is treated as a data-entry scale error and not counted as a restatement. That field is served as null in financials; its as-filed value is kept under data_quality.as_filed_unverified, and its name is listed in data_quality.values_withheld. Read a null there as withheld, not missing. The vintages response also lists such fields in fields_with_scale_corrections.
• Identity. The symbol is resolved to one security first. Financial statements are filed by the issuer, so every share class of one company returns the same figures, as financial_statement_grain states. A fund, warrant or preferred line returns security_type_not_covered instead of an empty panel.
• Coverage. When the archive was loaded it held about 1.03 million versions for 21,747 companies, with knowledge dates from 2018-01-01 and fiscal periods back to 1973. An as_of before the knowledge span cannot be answered; pit_coverage reports the current bounds, overall or for one ticker.

Examples#

Example 1: Get a full company snapshot#

Retrieve a complete fundamentals snapshot for Apple in one call.

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/company_full/AAPL" # Response structure (abbreviated):# {#   "ok": true,#   "timestamp": "2026-09-23T01:57:05Z",#   "ticker": "AAPL",#   "data": {#     "name": "Apple Inc.",#     "sector": "Consumer Goods",#     "industry": "Electronic Equipment",#     "full_time_employees": 150000,#     "latest_annual": { "fiscal_year": 2025, "revenue": 416161000000, "net_income": 112010000000, ... },#     "income_statement_ttm": { "fiscal_period": "TTM", "end_date": "2026-06-27", "revenue": 466823000000, "net_income": 128930000000, ... },#     "balance_sheet_mrq": { "fiscal_period": "Q3", "period": { "type": "point_in_time", ... }, "total_assets": 383266000000, ... },#     "cash_flow_ttm": { "operating_cash_flow": 146724000000, "free_cash_flow": 136683000000, ... },#     "ratios": { "fiscal_period": "Q3", "period": { "type": "quarter", ... }, "net_margin": 0.2723, "roe": 0.2784, "debt_to_equity": 0.7659, "units": { "roe": "fraction", "debt_to_equity": "multiple", ... }, ... },#     "growth": { "fiscal_year": 2025, "revenue_growth_yoy": 6.43, "eps_growth_yoy": 22.7, ... },#     "dividends": { "payout_ratio": 13.77, "dividends_paid_fiscal_year": ..., "dividends_paid_ttm": ..., "years_consecutive_growth": 5, ... },#     "dividend": { "status": "ok", "trailing_per_share": ..., "indicated_annual_per_share": ..., ... },#     ...#   }# }

ratios covers the latest reported quarter: margins and returns are fractions (0.2784 is 27.84%), and the current ratio and debt to equity are multiples, as ratios.units states. They are that one quarter's ratios, not annualised and not trailing twelve months: roe here is one quarter's return on equity. Trailing ratios are in ttm.ttm_ratios, in percent. growth covers the latest fiscal year and its values are percents (6.43 is 6.43%). payout_ratio is a percent too (13.77 is 13.77%).

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/fundamentals/company_full/AAPL",    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()body = r.json()company = body["data"]ttm = company["income_statement_ttm"]print(f"{body['ticker']}: {company['name']}")print(f"Revenue (TTM to {ttm['end_date']}): ${ttm['revenue'] / 1e9:.1f}B")print(f"Net margin ({company['ratios']['fiscal_period']}): {company['ratios']['net_margin']:.1%}")print(f"Revenue growth (FY{company['growth']['fiscal_year']}): {company['growth']['revenue_growth_yoy']:.1f}%")

Example 2: Screen stocks by multiple factors#

Find stocks with ROE of at least 15%, revenue growth of at least 10%, and at least 10 consecutive years of dividend growth. Percent filters use the same percent units as the response: roe_min_pct=15 means 15%, not 0.15. With no floor parameters, only common stock with at least a $300M market cap and $1M a day of dollar volume is returned, largest first.

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/screener?roe_min_pct=15&revenue_growth_min_pct=10&years_dividend_growth_min=10&limit=50" # Response structure (abbreviated; "..." stands for values not shown):# {#   "ok": true,#   "timestamp": "...",#   "filters": {#     "roe_min": 15.0,#     "revenue_growth_min": 10.0,#     "years_dividend_growth_min": 10#   },#   "filters_applied": [#     "roe >= 15% (each row's latest fiscal year (fiscal_year), not TTM; net income / average shareholders' equity)",#     ...#   ],#   "units": { "roe": "percent", "revenue_growth_yoy": "percent", "debt_to_equity": "multiple", ... },#   "sort_by": "market_cap_usd",#   "sort_by_requested": null,#   "sort_order": "desc",#   "floors": {#     "min_market_cap_usd": 300000000.0,#     "min_adv_usd": 1000000.0,#     "security_class": ["common"]#   },#   "total_matched": ...,#   "total_pages": ...,#   "items": [#     {#       "ticker": "MSFT",#       "name": "MICROSOFT CORP",#       "sector": "Technology",#       "fiscal_year": 2026,#       "roe": 34.04,#       "revenue_growth_yoy": 17.79,#       "payout_ratio": 19.77,#       "years_dividend_growth": 16,#       "listing_ticker": "MSFT",#       "security_class": "common",#       "price_usd": ...,#       "adv_21d_usd": ...,#       "market_cap_usd": ...,#       "reporting_currency": "USD",#       "revenue_usd": ...,#       "net_income_usd": ...,#       "fundamentals_stale": false,#       ...#     },#     ...#   ],#   "universe": { "candidate_set_complete": true, "excluded": { ... }, "liquid_without_market_cap": [ ... ], ... },#   "field_sources": { ... },#   "as_of": { "prices": "...", "shares_outstanding": "...", ... }# }

Each row reports its own fiscal_year, which can lag the calendar for companies with stale filings; fundamentals_stale is true when that fiscal period ended more than 18 months ago. Check it before comparing names. Compare size across rows on market_cap_usd, and revenue on revenue_usd, never on revenue.

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/fundamentals/screener",    params={        "roe_min_pct": 15,        "revenue_growth_min_pct": 10,        "years_dividend_growth_min": 10,        "limit": 50,    },    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()results = r.json()print(f"Found {len(results['items'])} dividend growers with ROE >= 15% and revenue growth >= 10%")for stock in results["items"][:5]:    print(f"  {stock['ticker']}: ROE {stock['roe']:.1f}%, "          f"revenue growth {stock['revenue_growth_yoy']:.1f}%, "          f"dividend growth {stock['years_dividend_growth']} years")

Example 3: Point-in-time, as-reported XBRL (no restatement look-ahead)#

Vendors serve restated numbers, the value a period shows today after later revisions, which bakes look-ahead bias into any backtest. SEC's companyfacts document carries the filed date on every fact, so ?as_of= returns exactly what was public on a given date. First discover the concept tag, then query it as of a historical date.

# 1. Discover the XBRL concepts Apple has filed (filter to net income)curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/companyfacts/AAPL?search=netincome" # Response structure:# {#   "ok": true,#   "timestamp": "2024-12-16T14:22:00Z",#   "ticker": "AAPL",#   "cik": 320193,#   "entity_name": "Apple Inc.",#   "n_concepts": 2,#   "concepts": [#     {#       "taxonomy": "us-gaap",#       "concept": "NetIncomeLoss",#       "label": "Net Income (Loss) Attributable to Parent",#       "units": ["USD"],#       "n_observations": 112,#       "first_period": "2008-09-27",#       "last_period": "2024-09-28"#     },#     { ... }#   ],#   "source": "sec_edgar_companyfacts_live",#   "as_of": "...", "last_filed": "...", "financial_facts_last_filed": "...", "is_stale": false, "freshness": { ... }# } # 2. Net income AS IT WAS PUBLIC on 2020-02-01, no later restatement leaks incurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/xbrl/AAPL/NetIncomeLoss?form=10-K&as_of=2020-02-01" # Response structure:# {#   "ok": true,#   "timestamp": "2024-12-16T14:22:10Z",#   "ticker": "AAPL",#   "cik": 320193,#   "entity_name": "Apple Inc.",#   "taxonomy": "us-gaap",#   "concept": "NetIncomeLoss",#   "units_available": ["USD"],#   "as_of": "2020-02-01",#   "mode": "latest_per_period",#   "n": 2,#   "rows": [#     {#       "unit": "USD",#       "start": "2018-09-30",#       "end": "2019-09-28",#       "val": 55256000000,#       "fy": 2019,#       "fp": "FY",#       "form": "10-K",#       "filed": "2019-10-31",#       "accn": "0000320193-19-000119",#       "frame": "CY2019",#       "period_fy": 2019,#       "period_fp": "FY",#       "period_months": 12#     },#     { ... }#   ],#   "source": "sec_edgar_companyfacts_live",#   "data_as_of": "...", "last_filed": "...", "concept_last_filed": "...", "is_stale": false, "freshness": { ... }, "field_notes": { ... }# }

Example 4: Business & geographic segments (4 credits, Starter and up)#

See where a company earns, revenue mix by region and by line of business, from the licensed segment archive. The archive lags by a few quarters, so with no year/date the latest available period is returned and the datadate served is reported.

# Latest available segment breakdown for Applecurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/segments/AAPL" # Response structure (abbreviated):# {#   "ok": true,#   "timestamp": "2024-12-16T14:22:20Z",#   "ticker": "AAPL",#   "gvkey": "001690",#   "company_name": "APPLE INC",#   "datadate": "2023-09-30",#   "fiscal_year": 2023,#   "mode": "latest_available",#   "currency": "USD",#   "n_segments": 9,#   "truncated": false,#   "segment_type_legend": {#     "BUSSEG": "business segment: line of business",#     "GEOSEG": "geographic segment: region"#   },#   "segments": {#     "GEOSEG": [#       { "segment_id": "01", "name": "Americas", "sales": 162560.0, "revenue": 162560.0,#         "operating_income": 60508.0, "geographic_type_code": "2", "geographic_type": null,#         "currency": "USD", "datadate": "2023-09-30" },#       { "segment_id": "03", "name": "Greater China", "sales": 72559.0, "revenue": 72559.0,#         "operating_income": 30328.0, "geographic_type_code": "3", "geographic_type": "non_domestic",#         "currency": "USD", "datadate": "2023-09-30" }#     ],#     "BUSSEG": [#       { "segment_id": "01", "name": "iPhone", "sales": 200583.0, "revenue": 200583.0, ... }#     ]#   },#   "available_datadates": ["...", "2022-09-30", "2023-09-30"],#   "source": "warehouse:segments-archive"# }

Example 5: What did the market know on a date? (3 credits, Pro and up)#

Pull Apple's last eight quarters as they stood on 2025-03-01, then check which of those figures have been revised since.

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/pit/AAPL?as_of=2025-03-01&periods=8" # The restatement trail for one of those quarterscurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/pit/AAPL/vintages?datadate=2024-12-31"

Example 6: Find a company, then pull its full picture (1 credit each)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/search?q=apple&limit=3"

Live response captured 2026-09-23, abbreviated:

{  "ok": true,  "timestamp": "2026-09-23T04:59:58.433896+00:00",  "query": "apple",  "items": [    { "ticker": "AAPL", "name": "Apple Inc.", "country": "USA", "industry": "Electronic Equipment", "sector": "Consumer Goods", "exchange": "NASDAQ", "is_sp500": true },    { "ticker": "AAPI", "name": "Apple iSports Group, Inc.", "country": "Australia", "industry": "Gaming Activities", "sector": "Consumer Cyclical", "exchange": "Other OTC", "is_sp500": false }  ]}

Then call /api/v3/fundamentals/full/AAPL for the bundle.

Related#