Source-backed disclosure resolution
Each observation connects the normalized value to the company disclosure or transparent calculation that supports it.
Software companies disclose operating measures across structured SEC facts, filing prose and tables, earnings releases, presentations, and prepared remarks. SoftwareIQ evaluates those materials together and resolves the best available disclosure into a canonical series rather than treating one automated filing feed as complete.
Reported observations retain a source metric key and source_check_id for evidence review. Calculated observations remain explicitly identified, publish the applicable formula, and are produced only when the required inputs and calculation controls are satisfied. A calculation does not replace a qualifying direct disclosure.
Structured facts, filing tables and narrative, earnings releases, and presentations are reconciled with source precedence and period consistency.
Issuer terminology, cohort thresholds, scope, units, and qualifiers remain attached to the canonical metric so normalization does not erase material differences.
Derived values expose their formula and required inputs, including cRPO, billings, bookings, mix, retention-efficiency, and cash-flow calculations.
Revenue and operating-KPI guidance retain issuance date, target period, range structure, basis, revision sequence, and linkage to realized results.
Operating KPI metric catalog
The catalog groups recurring multi-company disclosures into analytical families while preserving the identifiers and definitions needed for precise use.
Coverage is disclosure-led: a catalog entry describes a supported metric family, not a promise that every issuer reports it in every period. Company-specific ARR, revenue, customer, and retention measures are standardized where their economic meaning aligns; different thresholds or scopes remain separate metric IDs.
Revenue, demand, and contracted backlog
Reported and normalized measures used to evaluate growth, recurring scale, bookings, and forward revenue visibility.
| Metric family | Representative metric IDs | Basis | SoftwareIQ definition | Calculation, when applicable |
|---|---|---|---|---|
| Recurring, subscription, product, or cloud revenue | recurringRevenue, cloud, nonServices | Reported or normalized | The issuer's recurring or product-led revenue measure. Company terminology is retained while related disclosures are grouped for analytical discovery; unlike labels are not treated as identical. | — |
| Annual recurring revenue | arr | Reported | Contracted or run-rate recurring revenue under the issuer's disclosed ARR definition at period end. | — |
| ARR components | cloudArr and company-specific ARR metrics | Reported | Disclosed ARR attributable to a product, deployment model, or business line. Components are comparable only when scope and issuer definitions align. | — |
| Remaining performance obligations | rpo | Reported | Contracted revenue not yet recognized under the issuer's RPO disclosure. | — |
| Current remaining performance obligations | currentRpo | Reported preferred; derived fallback | RPO expected to be recognized within the disclosed near-term window, generally the next twelve months. | Direct disclosure is preferred. Fallback: rpo × disclosed next-12-month RPO percentage. |
| Calculated current billings | currentCalculatedBillings | Calculated | Revenue adjusted for the sequential or year-over-year change in current deferred revenue. | revenue + current deferred revenue − prior current deferred revenue |
| Calculated total billings | calculatedBillings | Calculated | Revenue adjusted for the change in current and non-current deferred revenue when both components are available. | revenue + change in current deferred revenue + change in non-current deferred revenue |
| Calculated bookings | calculatedBookings | Calculated | Revenue adjusted for the change in total RPO. | revenue + rpo − prior rpo |
| Current bookings proxy | currentCalculatedBookings | Calculated | Revenue adjusted for the change in current RPO. | revenue + currentRpo − prior currentRpo |
| Current RPO mix | currentRpoMix | Calculated | Share of total RPO expected within the current recognition window. | currentRpo ÷ rpo |
| RPO duration | rpoDuration | Calculated | RPO expressed relative to an annualized quarterly revenue run rate. | rpo ÷ (quarterly revenue × 4) |
Customers, cohorts, and retention
Company-disclosed customer populations and retention measures, normalized without erasing issuer-specific cohort definitions.
| Metric family | Representative metric IDs | Basis | SoftwareIQ definition | Calculation, when applicable |
|---|---|---|---|---|
| Total customers | customers | Reported | The issuer's disclosed customer count. Definitions may exclude free users, acquired populations, or selected products and remain qualified accordingly. | — |
| Customer spend or ARR cohorts | customersGt5k, customersGt10k, customersGt50k, customersGt100k, customersGt250k, customersGt300k, customersGt500k, customersGt1M, customersGt5M | Reported | Customers above the issuer's disclosed annualized spend, ARR, ACV, or revenue threshold. Threshold amount and measurement basis are retained; cohorts are not merged across unlike thresholds. | — |
| Customers above a usage threshold | customers10User | Reported | Customers meeting a disclosed seat or user threshold, such as more than ten users. | — |
| Paying users | payingUsers | Reported | Paid users or paid accounts under the issuer's stated definition. | — |
| Locations | locations | Reported | Customer locations, sites, or equivalent operating units under the issuer's disclosure. | — |
| Net revenue retention | nrr | Reported | Recurring revenue from an opening customer cohort after expansion, contraction, and churn, divided by the opening cohort value, subject to the issuer's definition. | — |
| Cloud net revenue retention | cloudNrr | Reported | NRR restricted to the issuer's cloud customer or revenue population. | — |
| Cohort-specific NRR | nrr10User, nrr50k, nrr100k | Reported | NRR for a disclosed usage or spend cohort. The cohort boundary remains part of the metric identity. | — |
| Gross revenue retention | grr | Reported | Opening recurring revenue retained before expansion, under the issuer's disclosed treatment of contraction and churn. | — |
| Revenue per customer | revenuePerCustomer | Calculated | Annualized revenue proxy divided by disclosed customers. | Quarterly: TTM best-revenue proxy ÷ customers; annual: fiscal-year best-revenue proxy ÷ customers |
| Customer acquisition payback | paybackPeriod | Calculated | Months of sales and marketing investment required to recover estimated incremental gross profit. Published only when required inputs pass calculation controls. | 12 × S&M ÷ (change in best-revenue proxy × gross-profit ratio); quarterly calculations use TTM inputs |
Adjusted P&L and cash-conversion inputs
Disclosure details and calculated measures that support software-specific profitability analysis without reproducing standard financial statements.
| Metric family | Representative metric IDs | Basis | SoftwareIQ definition | Calculation, when applicable |
|---|---|---|---|---|
| Stock-based compensation | stockBasedCompensation | Reported | Total stock-based compensation recognized during the period. | — |
| Functional stock-based compensation | sbc_cogs, sbc_rnd, sbc_sm, sbc_gna | Reported | SBC assigned to cost of revenue, R&D, sales and marketing, and G&A. These inputs support user-defined adjusted P&L analysis. | — |
| Capitalized software | capitalizedSoftware | Reported | Capitalized internal-use or software-development expenditure when separately disclosed. | — |
| Free cash flow | freeCashFlow | Calculated or issuer-reported context | Operating cash flow after capital expenditure, with capitalized software deducted when separately disclosed. | cashFlowFromOperations − capex − capitalizedSoftware; fallback: cashFlowFromOperations − capex |
Workforce structure
Reported operating capacity used to evaluate functional investment and productivity.
| Metric family | Representative metric IDs | Basis | SoftwareIQ definition | Calculation, when applicable |
|---|---|---|---|---|
| Total headcount | hc, employees | Reported | Employees at the disclosed date under the issuer's workforce definition. | — |
| Functional headcount | hcCogs, hcRD, hcSM, hcGA, hcSvc | Reported | Employees assigned to cost-of-revenue, R&D, sales and marketing, G&A, or professional-services functions where disclosed. | — |
| Geographic headcount | hcUS, hcInt | Reported | Employees assigned to U.S. or international populations under the issuer's geographic definition. | — |
Business composition and efficiency
Normalized mixes, transaction measures, and calculated operating-efficiency indicators.
| Metric family | Representative metric IDs | Basis | SoftwareIQ definition | Calculation, when applicable |
|---|---|---|---|---|
| Cloud revenue mix | cloudMix | Calculated | Cloud revenue as a share of total revenue. | cloud revenue ÷ revenue |
| Services revenue mix | serviceMix | Calculated | Services revenue as a share of total revenue. | services revenue ÷ revenue |
| Recurring revenue mix | recurringMix | Reported or calculated | Recurring revenue as a share of the relevant revenue base. | — |
| Transaction revenue mix | transactionMix | Reported or calculated | Transaction-based revenue as a share of the relevant revenue base. | — |
| Non-cloud revenue and ARR | nonCloud, nonCloudArr | Calculated | Residual revenue or ARR outside the disclosed cloud component. | revenue − cloud revenue; ARR − cloud ARR |
| Payment and commerce volume | gmv, gpv, gtv | Reported | Issuer-reported gross merchandise, payment, or transaction value. Each volume type remains a separate metric. | — |
| Merchant, subscription, and transaction components | merchantSolutions, subscriptionSolutions, transaction | Reported | Disclosed revenue or volume components for transaction-oriented software and payments businesses. | — |
| ARR concentration | perArr50k, perArr100k, perArr500k, perArrNewProducts | Reported | Share of ARR associated with a disclosed customer-spend cohort or newer product set. | — |
| Rule of 40 | ruleOf40 | Calculated | Revenue growth plus free-cash-flow margin. | revenue growth + free cash flow ÷ revenue; quarterly calculations use TTM inputs |
| Rule of X | ruleOfX | Calculated | Growth-weighted efficiency measure that applies a two-times weight to revenue growth. | 2 × revenue growth + free cash flow ÷ revenue |
| Bookings-weighted Rule of X | ruleOfXBookings | Calculated | Growth-weighted efficiency measure using the series-consistent bookings proxy. | 2 × best-bookings growth + free cash flow ÷ revenue |
| Q4 bookings ratio | q4Ratio | Calculated | Quarterly best-bookings proxy as a share of trailing-twelve-month best bookings; primarily used to evaluate Q4 seasonality. | quarterly best-bookings proxy ÷ TTM best-bookings proxy |
Guidance metric families
Guidance is organized by the measure management actually provides—not forced into a revenue-only model. Each observation retains its target period, basis, range or point structure, and revision sequence.
| Guidance family | Representative metric IDs | Basis | SoftwareIQ definition |
|---|---|---|---|
| Revenue and revenue growth | revenue, revenueGrowthYoY, revenueGrowthYoYCC | Guided | Total revenue outlook plus reported year-over-year and constant-currency growth targets. |
| ARR and ARR growth | arr, cloudArr, arrGrowthYoY | Guided | Period-end recurring-revenue targets and growth rates under the issuer's disclosed ARR scope. |
| Subscription, product, recurring, or cloud revenue | nonServices, cloud, recurringRevenue | Guided | Company-specific revenue outlook aligned to the operating measure management uses to frame the business. |
| Billings and bookings | calculatedBillings, calculatedBillingsGrowthYoY, bookings | Guided | Management outlook for billings or bookings, preserved under the disclosed definition and period basis. |
| RPO and cRPO | rpo, rpoGrowthYoY, currentRpo, currentRpoGrowthYoY, currentRpoMix | Guided | Backlog and near-term backlog targets, including growth or mix when management guides those measures. |
| Cash generation | cashFlowFromOperations, freeCashFlow | Guided | Operating- and free-cash-flow outlook under management's stated basis. |
| Customer and retention KPIs | customers, customersGrowthYoY, nrr, dbnrr, grossRetention | Guided when disclosed | Customer-count and retention targets captured when management provides an explicit outlook. |
| Other company-specific revenue measures | services, saasAndSupportRevenue and mapped revenue metrics | Guided | Issuer-specific revenue components retained as distinct canonical metrics rather than forced into total revenue. |
Observation, period, and revision semantics
Each row identifies what was measured, the period it represents, and whether the value was reported or calculated.
| Concept | Definition |
|---|---|
| Reported observation | A value disclosed by the company and normalized to a canonical metric, period, unit, and qualifier. The source metric key and evidence reference preserve the issuer's terminology and scope. |
| Calculated observation | A value produced from identified source observations under a maintained formula. It remains distinguishable from a direct disclosure and does not replace a qualifying reported value. |
| Fiscal period | The company reporting period represented by the value. Period start, period end, fiscal year, and fiscal quarter describe economic time; updated_at describes publication maintenance time. |
| Guidance issue time | The time management published an outlook. It is distinct from the target fiscal period and orders revisions for the same company, metric, and target. |
| Null | No defensible value is available for the stated company, metric, period, and qualifier. Null is not converted to zero and does not imply that the issuer reported no activity. |
| Correction or restatement | A maintained-history update caused by issuer revision, improved source evidence, mapping repair, or calculation correction. It is not a new economic observation or an immutable as-released vintage. |
The stable company_id is the cross-dataset company key. A ticker is retained for display and filtering but can change following a listing, acquisition, or corporate action. The canonical metric_id supports comparison; source_metric_key, unit, basis, and qualifiers retain disclosure-specific meaning.
Customer cohorts are separated when thresholds, currencies, product scope, or contract populations differ. Company-defined ARR and retention measures are mapped into common families only when their economic meaning is sufficiently aligned. Standardization provides a consistent research surface without representing nonidentical disclosures as identical.
Guidance preserves both the issued observation and its target period. Range endpoints remain source values; a midpoint is a calculated convenience. Revisions are linked rather than collapsed so model calibration can use the sequence of management expectations and the eligible realized result.
REST resources
Read-only resources return canonical facts separately from their definitions.
/v1/metric-definitionsDiscover canonical metrics and mapped source keys.
| Parameter | Required | Behavior |
|---|---|---|
| metric_id | No | Exact canonical metric identifier. |
| section | No | Definition grouping. |
/v1/kpi-factsReturn current annual and quarterly KPI observations. This is not a release-vintaged time series.
| Parameter | Required | Behavior |
|---|---|---|
| company_id / ticker | No | Company filter; company_id is preferred for persisted research. |
| metric_id | No | One or more canonical KPI IDs. |
| period_type | No | annual or quarterly. |
| period_start / period_end | No | Inclusive fiscal-period boundary filters. |
/v1/guidance-factsManagement guidance observations, revisions, and realized outcomes.
| Parameter | Required | Behavior |
|---|---|---|
| company_id | No | Stable company identifier. |
| metric_id | No | Canonical guided metric. |
| issued_after / issued_before | No | Inclusive guidance-issuance window. |
| target_period_end | No | Target reporting period. |
from decimal import Decimal
import requests
response = requests.get(
"https://api.softwareiq.io/v1/kpi-facts",
headers={"Authorization": f"Bearer {TOKEN}"},
params={"company_id": "siqco:example", "period_type": "quarterly"},
timeout=30,
)
response.raise_for_status()
facts = response.json()["data"]
values = [Decimal(row["value"]) for row in facts if row["value"] is not None]Data Warehouse table reference
The same logical contract is distributed through Snowflake and BigQuery.
COMPANIES
Grain: one current row per company_id. Stable key: company_id.
| Field | Logical type | Nullable | Definition |
|---|---|---|---|
| company_id | STRING | No | Stable SoftwareIQ company identifier and preferred join key. |
| stable_id | STRING | No | Stable mapping identifier; currently equal to company_id. |
| company_group_id | STRING | Yes | Identifier linking related current or prior corporate entities. |
| ticker | STRING | Yes | Current display ticker; not a durable join key. |
| company_name | STRING | No | Current company display name. |
| cik | STRING | Yes | SEC central index key when applicable. |
| cik_id | STRING | Yes | Normalized SEC filer identifier when applicable. |
| current_status | STRING | Yes | Current public, private, acquired, or other mapping status. |
| coverage | STRING | Yes | Coverage designation. |
| coverage_source | STRING | Yes | Origin of the coverage designation. |
| website_coverage | STRING | Yes | Website publication state. |
| acquisition_coverage_type | STRING | Yes | Acquisition-related coverage behavior. |
| market | STRING | Yes | Primary market classification. |
| industry | STRING | Yes | Current industry classification. |
| sub_industry | STRING | Yes | Current sub-industry classification. |
| category | STRING | Yes | Current SoftwareIQ category. |
| reporting_currency | STRING | Yes | Primary reporting currency. |
| year_founded | INTEGER | Yes | Reported or mapped founding year. |
| ai_native | BOOLEAN | Yes | Current AI-native company designation. |
| taxonomy_version | STRING | Yes | Company taxonomy version. |
| deployment_origin | STRING | Yes | Mapped deployment origin. |
| tech_stack | STRING | Yes | Canonical JSON string for flexible tech-stack metadata. |
| content_hash | STRING | No | Deterministic content hash used for publication integrity. |
METRIC_DEFINITIONS
Grain: one row per metric_id. Stable key: metric_id.
| Field | Logical type | Nullable | Definition |
|---|---|---|---|
| metric_id | STRING | No | Canonical KPI identifier used for normalized analysis. |
| display_name | STRING | No | Human-readable metric label. |
| section | STRING | Yes | Research display grouping. |
| statement | STRING | Yes | Associated statement or analytical group. |
| format | STRING | Yes | Expected presentation format. |
| display_order | INTEGER | Yes | Suggested display order within a section. |
| source_metric_keys | STRING | Yes | Canonical JSON string containing mapped source keys. |
| content_hash | STRING | No | Deterministic publication hash. |
KPI_FACTS
Grain: one current normalized metric observation per company and fiscal period. Stable key: kpi_fact_id.
| Field | Logical type | Nullable | Definition |
|---|---|---|---|
| kpi_fact_id | STRING | No | Stable identifier for the current normalized observation. |
| company_id | STRING | No | Joins to COMPANIES.COMPANY_ID. |
| ticker | STRING | Yes | Convenience display ticker. |
| metric_id | STRING | No | Joins to METRIC_DEFINITIONS.METRIC_ID. |
| source_metric_key | STRING | No | Original internal metric key retained for lineage, not canonical comparisons. |
| period_type | STRING | No | Annual or quarterly observation grain. |
| period_label | STRING | Yes | Human-readable fiscal-period label. |
| period_start | DATE | Yes | Known start of the represented fiscal period. |
| period_end | DATE | Yes | Known end of the represented fiscal period. |
| fiscal_year | INTEGER | Yes | Company fiscal year. |
| fiscal_quarter | INTEGER | Yes | Company fiscal quarter for quarterly observations. |
| value | DECIMAL | Yes | Numeric observation. Null is not zero. |
| unit | STRING | Yes | Currency, percentage, count, multiple, or other measurement unit. |
| value_qualifier | STRING | Yes | Qualification such as reported, calculated, or disclosure-specific context. |
| source_resolved_metric_id | STRING | Yes | Resolved internal source identifier. |
| source_check_id | STRING | Yes | Identifier for the analyst-facing evidence record. |
| source_check_url | STRING | Yes | Relative SoftwareIQ source-check URL. |
| updated_at | TIMESTAMP | Yes | Latest observation update timestamp; not an original release vintage. |
| content_hash | STRING | No | Deterministic publication hash. |
GUIDANCE_FACTS
Grain: one issued guidance observation for one company, metric, and target period.
| Field | Logical type | Nullable | Definition |
|---|---|---|---|
| guidance_fact_id | STRING | No | Stable identifier for one guidance observation. |
| company_id | STRING | No | Stable company join key. |
| metric_id | STRING | No | Canonical revenue or operating-KPI target. |
| issued_at | TIMESTAMP | No | Public issuance timestamp used to order revisions. |
| target_period_type | STRING | No | Quarter, fiscal year, or other explicitly defined target period. |
| target_period_start | DATE | Yes | Target period start when resolved. |
| target_period_end | DATE | Yes | Target period end when resolved. |
| guidance_type | STRING | No | Range, point, floor, ceiling, or qualitative. |
| low_value | DECIMAL | Yes | Normalized lower bound. |
| high_value | DECIMAL | Yes | Normalized upper bound. |
| midpoint_value | DECIMAL | Yes | Calculated midpoint where meaningful. |
| unit | STRING | Yes | Unit applying to the values. |
| basis | STRING | Yes | GAAP, non-GAAP, constant-currency, or other disclosed basis. |
| prior_guidance_fact_id | STRING | Yes | Previous guidance observation in the revision chain. |
| actual_kpi_fact_id | STRING | Yes | Realized KPI observation when available. |
| source_check_id | STRING | Yes | Evidence-lineage identifier. |
| updated_at | TIMESTAMP | No | Publication update timestamp. |
| content_hash | STRING | No | Deterministic publication hash. |
Research conventions
A small set of conventions preserves comparability across companies, periods, and model runs.
- Retain
updated_atand the extract timestamp when a workflow requires a reproducible historical research state. - Treat null as not disclosed or unavailable for the stated grain; it is distinct from a reported zero.
- Use
value_qualifierto distinguish directly reported values from calculated observations. - Align guidance comparisons by target period, unit, GAAP or non-GAAP basis, currency treatment, and metric scope.