---
title: "Check up to 20 claims"
method: POST
path: "/api/v1/check"
---

# Check up to 20 claims

`POST /api/v1/check`

## Request

- Base URL: `https://invokely.ai`
- URL: `https://invokely.ai/api/v1/check`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
  - none

The same check as GET for a batch: {"claims": [{indicator, place, value, ...}], "citation_style"?}. One call is metered per 5 claims; unverifiable claims are not charged.

## Request body

- object
  - `claims` object[], required: 1 to 20 claims, each checked on its own.
    - `indicator` string, required: Indicator id, for example "population", "unemployment_rate", "cpi_annual_change", "gdp_usd". Call search_indicators first when unsure.
    - `place` string, required: Place name or id as in get_value: "Texas", "Spain", "United States", "Mataró", "es-prov-08", "fips:48453".
    - `period` string: Only when the claim names one: "2026" (year), "2026-Q2" (quarter), "2026-S1" (half), "2026-08" (month). Leave it out, or pass "latest", for claims in the present tense ("is", "has").
    - `value` union, required: The number as written, without the scale word or the % sign: 31 for "31 million", 3.2 for "3.2%". Digits with a dot for decimals and no separators: convert "31,290,831" to 31290831, a decimal comma ("3,4%" in Spanish) to 3.4 and a thousands dot ("1.200") to 1200; exponents, words and symbols are refused. A string keeps trailing zeros ("3.40"), which state precision. Negative for a fall in a change claim. For rank, the position (3 for "third highest").
      - number
      - string
    - `unit_hint` 'percent' | 'percentage_points' | 'units' | 'thousands' | 'millions' | 'billions' | 'trillions': The scale word or unit written: percent (%), percentage_points ("points"), thousands, millions, billions, trillions, or units (a plain number). Omit when nothing is written.
    - `currency` string: ISO 4217 code when the claim is money: "USD" for $, "EUR" for €. Invokely does not convert currencies; a claim in another currency than the indicator is unverifiable, with indicators in that currency suggested.
    - `qualifier` 'exact' | 'about' | 'at_least' | 'at_most': Omit for a plain statement. exact only when the claim says "exactly" (trailing zeros then count as digits); about ("about", "around", "nearly", "roughly"); at_least ("more than", "over", "above", "at least"); at_most ("less than", "under", "below", and "in the top 3" for ranks). Bounds are inclusive.
    - `kind` 'level' | 'yoy' | 'yoy_diff' | 'pct_change' | 'diff' | 'per_capita' | 'per_1000' | 'per_100k' | 'rank': level (default): the figure itself. yoy: % change from a year earlier ("prices rose 3% over the year"). pct_change: % change from the previous period. yoy_diff, diff: the same changes in the indicator unit, points for rates ("unemployment fell 0.4 points"). per_capita, per_1000, per_100k: a total divided by population. rank: position among places ("third highest").
    - `rank_within` string: rank only: the area of the ranking, for example "EU" for "among EU countries", "United States" for states, "Texas" for its counties. Required below country level; omitted for countries means every country.
    - `rank_order` 'highest' | 'lowest': rank only: highest (default) or lowest first.
    - `country` string: Optional ISO 3166-1 alpha-2 code to disambiguate the place.
    - `as_of` string: When the claim was made or published, as a UTC date ("2026-09-15") or date and time with a zone. A claim that was right with the figures published then but was revised or superseded since comes back outdated with accurate_when_made true, and vintage shows then versus now. Level claims only.
    - `text` string: Optional original sentence. Echoed back for your records and never interpreted.
    - `tolerance` object: Optional. Replaces the approximately_accurate band (default: 2% of the official value or twice the rounding band, whichever is larger). Never narrower than the rounding the claim implies.
      - `relative` number: Share of the official value, for example 0.05 for 5%.
      - `absolute` number: In the same unit as value and unit_hint.
  - `citation_style` 'apa' | 'mla' | 'chicago' | 'harvard' | 'bibtex' | 'ris' | 'all': Optional. Adds official.source.citations in this style, or in all six with "all".
  - `locale` 'en' | 'es'

## Response `200`

Success. The body is {"data": ...}; the remaining allowance is in the x-invokely-remaining header.

- Data
  - `data` unknown, required

## Other responses

- `400`: Invalid argument (INVALID_ARGUMENT).
- `401`: The API key or token is invalid or revoked (UNAUTHORIZED).
- `402`: Allowance used up (QUOTA_EXHAUSTED), or the plan does not include the REST API (PLAN_REQUIRED: Free keys; use the MCP server or upgrade to Builder).
- `404`: Unknown indicator or place, or no data (INDICATOR_NOT_FOUND, PLACE_NOT_FOUND, AMBIGUOUS_PLACE, NO_DATA). hint and suggestions say what to try next.
- `413`: Body over 64 KB (PAYLOAD_TOO_LARGE).
- `415`: POST needs content-type: application/json (UNSUPPORTED_MEDIA_TYPE).
- `429`: Rate limited (RATE_LIMITED). Retry after retry_after_seconds.

---

[API](https://skmtc.dev/invokely/apis/invokely-statistics-api.md) · [All operations](https://skmtc.dev/invokely/apis/invokely-statistics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/invokely/apis/invokely-statistics-api/revisions/3b0f775bccb6?raw)