--- title: "Verify a batch of claimed figures to fact-check a whole draft (the API's only non-GET route)" method: POST path: "/v1/verify_claims" --- # Verify a batch of claimed figures to fact-check a whole draft (the API's only non-GET route) `POST /v1/verify_claims` ## Request - Base URL: `https://statcite.com` - URL: `https://statcite.com/v1/verify_claims` - Auth: none declared Extract every checkable macro claim from a draft (indicator + country + period + claimed value) and submit up to 15 together. Each claim gets the same verdict engine as /v1/verify. Results return in input order with a verdict-count summary. A claim that cannot be resolved reports its error in place without failing the batch. The 15-claim cap reflects the free-tier upstream subrequest budget, so split larger drafts into batches. ## Request body - object - `claims` object[], required: The claims extracted from the draft, in the order they appear (max 15 per call). - `indicator` string, required: Registry key (inflation_cpi, gdp_growth, …) or explicit series id (worldbank/FP.CPI.TOTL.ZG, imf/NGDP_RPCH, dbnomics/…). fred/… ids are recognised but always decline, because FRED is disabled. - `country` string: ISO3/ISO2 code or English name; required for registry indicators / worldbank series - `period` string, required: Period of the claim, usually a year, e.g. 2024 - `claimed_value` number, required: The value as claimed, in the series' own units - `tolerance_abs` number: Optional absolute tolerance in series units - `tolerance_pct` number: Optional relative tolerance in percent - `as_of` string: Verify this claim against the IMF WEO/Fiscal Monitor edition current as of this date (e.g. '2019-04') instead of today's live data. Only the 6 WEO-dated registry indicators support it. They are served from the IMF's own vintage dataflows first, with DBnomics dated editions as the deep archive. - `strict_source` boolean: Apply reproducibility mode to every claim in the batch: never verify against a fallback source, and let such claims error in place. Without it, a claim served from a transient-failure fallback returns cannot_verify with the fallback value as indicative. ## Response `200` Batch verification result: verdict-count summary plus per-claim results in input order - object - `summary` object - `total` integer - `match` integer - `close` integer - `mismatch` integer - `cannot_verify` integer - `error` integer - `results` object[]: One entry per claim, in input order. ok:true entries carry the full verification payload; ok:false entries carry a per-claim error message (errors never sink the rest of the batch). - `ok` boolean - `claim` object - `verification` VerifyResult - `verdict` 'match' | 'close' | 'mismatch' | 'cannot_verify' - `claimed_value` number - `official_value` number, nullable - `is_projection` boolean: True when the matched official observation is an IMF WEO/Fiscal Monitor estimate/projection, not a final outturn. Kept for compatibility; observation_status carries the finer-grained classification. - `observation_status` 'actual' | 'modeled_estimate' | 'estimate_or_actual' | 'projection' | 'unknown': The honest status of the matched observation, as one of five values. 'actual' means a series StatCite classifies as outturn data (registry World Bank indicators not flagged as modelled, and explicit worldbank/ WDI ids), subject to routine revision. 'modeled_estimate' (added 1.4.1) means the registry flags the indicator as a modelled series, such as the World Bank's ILO-modelled unemployment and labour force participation estimates. That is a published figure, but a model output rather than a measured outturn. 'estimate_or_actual' means an IMF WEO/Fiscal Monitor observation before the projection boundary. The IMF's true latest-actual year varies by country and is not exposed by the data path, so recent values may be staff estimates, and this should never be read as a confirmed actual. 'projection' means at or after the heuristic boundary. 'unknown' means no observation matched the period, or the series is an explicit id outside StatCite's classification. Arbitrary DBnomics series can be forecast datasets, so consult the source. - `status_method` 'horizon_heuristic' | 'as_published': How observation_status was determined. 'horizon_heuristic' applies to IMF WEO/Fiscal Monitor series, where the boundary is derived from the response's own data: the payload's projection horizon on the DataMapper channel, and the dataset-code vintage year on the DBnomics channel. It is a heuristic, not IMF per-country metadata. 'as_published' applies otherwise. - `period` string - `difference` number, nullable - `relative_difference_pct` number, nullable - `explanation` string - `diagnostics` string[] - `series` object - `country` object - `citation` Citation: Every numeric payload carries one of these. Reproduce citation_text when presenting the number. - `source` string - `dataset` string - `series_id` string - `series_name` string - `source_url` string - `api_url` string - `license` string - `attribution` string - `retrieved_at` string - `citation_text` string - `notices` string[] - `export_formats` object: Ready-to-paste citation strings derived from this citation's own fields, so they can never disagree with citation_text. - `bibtex` string - `apa` string - `notes` string[] - `fallback_used` boolean: Present and true when the official value came from a fallback source because the primary failed. A transient primary failure demotes the verdict to cannot_verify with the fallback value reported as indicative (a substitute source can differ by definition or vintage far beyond the verdict bands, and the primary may recover and serve a different number); when the primary permanently lacks the series/country, the fallback is the stable serving source and the verdict is judged normally with disclosure. Absent otherwise. - `as_of` object: Present only when the as_of parameter was used, and absent otherwise. It marks historical IMF-VINTAGE verification: the verdict was checked against a dated IMF WEO edition, not today's live data. - `requested` string: The as_of date as passed by the caller. - `resolved_vintage` string: The IMF WEO edition (YYYY-MM) resolved from it. - `resolution` 'conservative_month_calendar': How the vintage was resolved: with a conservative month calendar (editions flip on 1 May and 1 November), NOT the IMF's exact release days. So a date late in a release month resolves to the previous edition even if the new one had already been published. A note discloses this for dates inside release months. - `verification_scope` 'imf_weo_historical_vintage': What was verified against: the IMF WEO historical archive, the only dated-vintage source this server has. - `normal_primary_source` string: The source the live (non-as_of) path serves this indicator from first (e.g. 'World Bank WDI', 'IMF Fiscal Monitor (via the DataMapper API)'). - `source_changed_for_as_of` boolean: True when the live primary differs from the WEO archive by source or IMF database. A claim originally made from the live primary can then legitimately differ from the WEO edition for methodological reasons, not only because of revisions. - `error` string - `note` string: Present when some claims were verified against IMF WEO/Fiscal Monitor projections rather than outturns ## Other responses - `400`: Malformed, missing, unknown or repeated query parameter. The message names the parameter and lists what the route accepts. - `405`: Method not allowed. This endpoint accepts POST only, and GET returns usage advice. - `413`: The request body is over 262,144 bytes. Fifteen claims take a few KB. The error code is invalid_body. - `415`: Unsupported media type. Set content-type: application/json. - `422`: The request was well formed but cannot be answered, e.g. the source does not publish this series for this economy. --- [API](https://skmtc.dev/statcite/apis/statcite-api.md) · [All operations](https://skmtc.dev/statcite/apis/statcite-api/llms.txt) · [OpenAPI document](https://skmtc.dev/statcite/apis/statcite-api/revisions/8993772a4e80?raw)