Skip to content
Sign in — free

The figure check API, for developers and agents

Send a ticker and up to 20 claims. Each claim is a stated figure, a growth or margin computed from filed figures, or an event such as a restatement. Each comes back with a verdict, the accession of the filing it was read from when one was read, and a receipt written on a hash chain. The check compares a number with a filing and leaves the company and the number unjudged.

What comes back

The response holds receipt and verdicts, one verdict per claim in the order sent. Each verdict is one of these fixed strings.

matches_filing
The value equals the filed value in force, equals it rounded to the precision the claim states, or sits within 0.5% of it. The statement says which, and names the accession.
first_filed_differently
The value equals an earlier filing of the period that a later filing replaced.
contradicted
The value differs from every filed value. The statement gives the value in force and the accession it was read from. For an event claim, a filing of that kind was found and the statement names the newest one.
not_on_file
The filings read hold facts for other periods only. The statement lists the periods that are on file.
refused
The claim was set aside, and the statement says why: for example a filer reporting in another currency, a non-GAAP measure, an unknown line item, or a source that held too little to read. The refusal is kept in the receipt.
absent_in_read
Event claims only. Every filing dated inside the window could be read, and the statement reports the list those filings made for the kind asked about.

The receipt carries the engine version and links to the previous receipt by hash. Each response carries a verify_command that re-derives your chain offline. The steps for the public error record are on its page.

Three steps

  1. Try it free. GET /check/public takes a single figure and needs no account. Each address gets 20 checks per 30 days.
  2. Sign in, open Settings, then API keys, and make a key. The key is shown once.
  3. Call POST /v1/resolve with the header X-Api-Key and the same body as the check on this site.
curl "https://stockonomy.up.railway.app/check/public?ticker=AAPL&concept=revenue&fiscal_year=2023&value=383285000000"
curl -X POST https://stockonomy.up.railway.app/v1/resolve \
  -H "X-Api-Key: $STOCKONOMY_API_KEY" -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL", "claims": [{"type": "figure", "concept": "revenue", "fiscal_year": 2023, "value": 383285000000}, {"type": "growth", "concept": "revenue", "fiscal_year": 2023, "value": -2.8}]}'
import json, os, urllib.request

body = {"ticker": "AAPL", "claims": [{"type": "figure", "concept": "revenue", "fiscal_year": 2023, "value": 383285000000}, {"type": "growth", "concept": "revenue", "fiscal_year": 2023, "value": -2.8}]}
req = urllib.request.Request(
    "https://stockonomy.up.railway.app/v1/resolve", data=json.dumps(body).encode(),
    headers={"X-Api-Key": os.environ["STOCKONOMY_API_KEY"], "Content-Type": "application/json"})
with urllib.request.urlopen(req) as r:
    out = json.load(r)
for v in out["verdicts"]:
    print(v["verdict"], v.get("accession"), v.get("statement"))

Claim shapes

A figure is in US dollars, and in shares for diluted_shares. Growth and margin values are percentages. Any claim may add as_of (a date) to be read against the filings dated before it.

{"type": "figure", "concept": "revenue", "fiscal_year": 2023, "value": 383285000000}
{"type": "growth", "concept": "revenue", "fiscal_year": 2023, "value": -2.8}
{"type": "no_restatement", "since_year": 2021}

Line items for figure and growth: buybacks, capex, cost_of_revenue, diluted_shares, eps_diluted, gross_profit, long_term_debt, net_income, operating_cash_flow, operating_income, revenue, stock_based_compensation, total_assets. Margin takes a dollar flow other than revenue. A figure may also be segment_revenue with member, the XBRL member name as filed, and a quarter or year to date uses period and period_end in place of fiscal_year; growth and margin name fiscal_year. Add rounded_to to state the precision the writer rounded to. Event kinds: no_restatement, no_auditor_change, no_bankruptcy, no_delisting_notice, no_late_filing, each with since_year. Events are read for the last 7 calendar years.

Allowances

Each key gets 10 calls a minute and 500 a day. All keys of one owner share 20 a minute and 1000 a day. All keys together share 30 a minute and 5000 a day. A call over any of them answers 429 with a Retry-After (a free plan may also carry a monthly receipt allowance), writes no receipt, and reads no filing. A source that is down answers 503 and writes no receipt.

Verify us

For machines

/openapi.json describes both operations. /llms.txt summarizes this page for agents.