--- title: "Get entity financials" method: GET path: "/api/v1/entities/{entity_id}/financials" tags: ["Financials"] --- # Get entity financials `GET /api/v1/entities/{entity_id}/financials` ## Request - Base URL: `https://api.hub-equity.com` - URL: `https://api.hub-equity.com/api/v1/entities/{entity_id}/financials` - Auth: HTTP bearer Retrieve normalized financial data for an entity. Accepts UUID or ticker. ## Path parameters - `entity_id` string, required ## Query parameters - `years` integer: Number of years. `99` = all years available. - `category` string: Category filter - `currency` string, nullable: Display currency (ISO 4217, e.g. USD, EUR). Defaults to entity's native currency. - `rate_method` string: FX conversion method: 'ias21' (IAS 21 dual-rate, default), 'spot' (single closing rate), 'native' (no conversion). - `constant_currency_base_year` integer, nullable: Translate all years using the base year's FX rate to isolate organic growth from currency moves. Each MetricValue returns reported_value + fx_impact alongside the constant-currency value. - `end_year` integer, nullable: Anchor the rolling window at this fiscal year (inclusive). When set, the response returns up to `years` periods ending at `end_year` instead of the latest N. - `tiers` string, nullable: Comparability tier filter (comma-separated subset of `core,extended,detail`). Omit ⇒ serve every tier (each metric still carries its own `tier` in the envelope). A cross-entity consumer (compare / screener / SDK) passes `tiers=core` (or `core,extended`) to guarantee comparability. Fail-open: a metric whose tier is unknown is treated as `core` and never silently hidden. - `view` string: Payload shape. `full` (default) returns every field (audit / quality / provenance / per-cell FX metadata). `compare` returns only the comparison essentials (headline value + formatting + restatement flags + column-header metadata), dropping the audit metadata and every null field. ~8x smaller decoded — use it for cross-entity fan-out where full depth is reached on a follow-up single-entity call. ## Response `200` Successful Response - ApiResponseFinancialsResponse - `success` boolean, required - `data` FinancialsResponse: Financials response with metrics. - `entity_id` string, required - `entity_name` string, required - `currency` string, nullable, required - `periods` Period[], required - `fiscal_year` integer, required - `period_end` string, required - `filing_id` string, required - `metrics` Metric[], required - `code` string, required - `name` string, required - `name_fr` string, nullable, required - `category` string, required - `priority` integer, required - `data_type` string, required - `original_qname` string, nullable - `description` string, nullable - `is_derived` boolean - `formula` string, nullable - `tier` string - `typical_period` string, nullable - `confidence_score` number, nullable - `extraction_method` string, nullable - `calculation_details_by_year` object, nullable - `original_qname_by_year` object, nullable - `values` MetricValue[], required - `fiscal_year` integer, required - `value` number, nullable, required: The value as printed in the filing of that fiscal year, never changed. When a later filing restated it, the number to cite is `display_value`. - `formatted` string, required: `display_value`, formatted for display. - `change_percent` number, nullable, required - `change_direction` 'up' | 'down', nullable, required - `sign_changed` boolean - `is_amendment` boolean - `is_restated` boolean - `restated_value` number, nullable - `restatement_delta_pct` number, nullable - `display_value` number, nullable: The served value, the one to cite: `restated_value` when a later filing restated the cell, `value` otherwise. Every other endpoint serves this number. - `overlay_source` 'none' | 'row' | 'log', nullable - `served_filing_id` string, nullable - `currency` string, nullable - `original_currency` string, nullable - `period_type` 'instant' | 'duration', nullable - `fiscal_period_type` 'FY' | 'Q1' | 'Q2' | 'Q3' | 'Q4' | 'H1' | 'H2', nullable - `period_end` string, nullable - `reported_fiscal_year` integer, nullable - `original_value` number, nullable - `conversion_rate` number, nullable - `conversion_rate_kind` 'spot' | 'avg_period', nullable - `conversion_rate_date` string, nullable - `reported_value` number, nullable - `fx_impact` number, nullable - `confidence` number, nullable - `extraction_method` string, nullable - `confidence_v2` ConfidenceV2: Confidence score for a served value. - `score` number, required - `components` ConfidenceComponents, required: Sub-scores of the confidence score. - `s_tier` number, required - `s_identity` number, required - `s_agree` number, required - `s_reliability` number, required - `s_structure` number, nullable - `model_version` string, nullable - `would_change` boolean - `argmax_source` string, nullable - `enforced` boolean - `enforced_by` string, nullable - `replaced_value` string, nullable - `replaced_source` string, nullable - `would_change_structure` boolean, nullable - `provenance_method` string, nullable - `identity_check` IdentityCheck: Whether the served value reconciles with the accounting identities it takes part in. ``status``: - ``reconciles``: at least one accounting identity holds for this value. - ``violation``: every computable identity failed; ``identity``/``expected``/ ``actual``/``delta_pct`` give the closest one. - ``deferred``: the filer's own calculation linkbase declares this concept a total, so a cross-statement identity does not apply; not an error. ``None`` when no check is available for the value. - `status` 'reconciles' | 'violation' | 'deferred', required - `identity` string, nullable - `expected` number, nullable - `actual` number, nullable - `delta_pct` number, nullable - `deferred_reason` string, nullable - `outlier_yoy` OutlierYoY: Isolated year-over-year spike: the value moved by more than a threshold against the prior fiscal year and the following year returned to the prior level, i.e. an isolated spike, not a level shift. A flag, not an error: on volatile cash-flow lines an isolated spike is often a genuine one-off (acquisition, buyback). The value is never corrected. ``None`` when the value carries no flag. - `delta_pct` number, required - `prev_value` number, nullable - `next_value` number, nullable - `baseline_return_pct` number, nullable - `not_reported` boolean - `not_reported_reason` 'not_reported' | 'no_longer_reported' | 'not_applicable' | 'zero' | 'combined_into', nullable - `not_reported_detail` string, nullable - `name_period_start` string, nullable - `name_period_end` string, nullable - `name_negated` string, nullable - `name_total` string, nullable - `labels_by_section` object - `categories` CategoryInfo[], required - `code` string, required - `name` string, required - `name_fr` string, nullable, required - `metrics_count` integer, required - `original_currency` string, nullable - `display_currency` string, nullable - `conversion_method` 'ias21' | 'spot' | 'native', nullable - `constant_currency_base_year` integer, nullable - `fx_unconverted` string[], nullable - `error` ApiError: API error details. - `code` string, required - `message` string, required - `details` object, nullable - `meta` ApiMeta: API response metadata. Pagination fields (``page`` / ``per_page`` / ``total``) are populated on collection endpoints only. They are omitted from the payload on single-resource endpoints. - `timestamp` string, date-time - `request_id` string, nullable - `page` integer, nullable - `per_page` integer, nullable - `total` integer, nullable - `links` ApiLinks: HATEOAS-style pagination cursors. Host-relative path + query links for a collection page. Present on collection endpoints, ``null`` fields where a page doesn't exist (``next`` on the last page, ``prev`` on the first). The whole ``links`` object is omitted from single-resource responses (see ``ApiResponse`` serializer). - `self` string, nullable - `first` string, nullable - `prev` string, nullable - `next` string, nullable - `last` string, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/hub-equity/apis/hub-equity-api.md) · [All operations](https://skmtc.dev/hub-equity/apis/hub-equity-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hub-equity/apis/hub-equity-api/revisions/e8eeda5dc13e?raw)