ORSF API — REST API for Slovak companies

What does ORSF API do?

ORSF aggregates 14 Slovak state registers into a single REST API and a queryable dataset. Three access modes:

• REST API — JSON over HTTPS, anonymous read on public endpoints (OpenAPI 3.1)
• MCP server — for AI agents (Claude, Cursor, Zed, Continue, Windsurf); one-line install
• CLI — npx @orsf/cli for shell-based exploration

All data is sourced from official public registers and carries lineage (source + fetchedAt per record). License: CC-BY 4.0 — attribute ORSF in your application.

ORSF API vs alternatives

As of 2026-05-27. For legally binding extracts use ORSR directly.

60-second quickstart

Three commands, no auth, no keys.

curl https://api.orsf.sk/v1/companies/55609830

curl 'https://api.orsf.sk/v1/search?q=8888'

curl https://api.orsf.sk/v1/stats/summary

Want to try without leaving this page? Jump to the Live playground.

Authentication

Most endpoints are public. Authentication is required only for person-level data and write actions:

Sign in via POST /api/auth/sign-in/email. Server returns a session cookie:

Set-Cookie: __Secure-orsf.session_token=...; Path=/; HttpOnly; Secure; SameSite=Lax

Pass the cookie on subsequent requests. There are no API keys or bearer tokens currently — sessions are the only auth method.

Endpoints

Full reference. See OpenAPI 3.1 spec for the machine-readable form.

GET /v1/searchpublic

Fulltext search over company names + IČO fast-path (numeric query → direct lookup).

curl 'https://api.orsf.sk/v1/search?q=poistovna&register=Obchodný%20register&limit=5'

GET /v1/companies/{ico}public

Full company record — identity, address, financial statements, business activities, VAT registration.

roles array is empty for anonymous (rolesLocked: true); sign in to see directors/officers.

curl https://api.orsf.sk/v1/companies/55609830 | jq '.name, .nationalId, .statusCode'

GET /v1/companies/{ico}/graphauth

Connection graph (Sigma.js / graphology compatible). Nodes + edges for company ↔ persons ↔ other companies. Depth 1-3.

GET /v1/persons/{id}auth

Person record with all known company roles. id is internal UUID returned from /v1/companies/{ico}.roles[].person.id.

GET /v1/stats/summarypublic

Aggregate counts (companies, filings, persons). Cached 5 min, approximate counts (within ~5%).

GET /v1/stats/districtspublic

Companies per NUTS LAU1 district. ?includeAll=true to include sole traders + non-business orgs.

GET /v1/labels?locale=en|skpublic

Localized human labels for enum codes. Fetch once at app startup, cache. Returns:

{
  "locale": "en",
  "status": { "active": "Active", "dissolved": "Dissolved", ... },
  "register": { "commercial": "Commercial Register", ... },
  "kind": { "company": "Company", "sole_trader": "Sole trader", "other": "Other" }
}

Field naming

Every Slovak field name in our responses has an English canonical alias. New clients should use the English form; legacy Slovak names will work forever. Full convention at docs/api-conventions.md.

Enum codes

Enum-like fields expose three forms: raw (from source), xxxCode (stable English machine code), and a localizable label via /v1/labels.

statusCode

registerCode

Errors

JSON error shape (Fastify default + our additions):

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Company with ID 12345678 not found."
}

Common status codes

Rate limits

Need higher limits for legitimate bulk use? Email [email protected].

MCP server (for AI agents)

The Model Context Protocol server exposes ORSF as tool-calls for LLM agents. Works with Claude Code, Claude Desktop, Cursor, Continue, Windsurf, and any MCP-compatible client.

Claude Code

claude mcp add orsf -- npx -y @orsf/mcp-server

Claude Desktop / Cursor / Windsurf

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (or platform equivalent):

{
  "mcpServers": {
    "orsf": {
      "command": "npx",
      "args": ["-y", "@orsf/mcp-server"]
    }
  }
}

Available tools

• search_companies — fulltext + filters
• get_company — full record by IČO
• get_company_graph — connection graph
• get_person — by UUID (auth required)
• get_person_graph — person-centric graph (auth required)
• get_stats — aggregate counters

MCP server is open-source on GitHub. Runs locally; never sends prompts to any third party — only ORSF JSON API.

CLI tool

Shell-based access without writing code:

npx @orsf/cli search "poistovna"
npx @orsf/cli company 55609830
npx @orsf/cli graph 55609830 --depth 2

Same data as REST API. Output is pretty-printed JSON or table form (with --format=table).

Pagination

List endpoints support limit + offset (offset-based pagination).

# First page
curl 'https://api.orsf.sk/v1/search?q=sro&limit=20&offset=0'

# Next page
curl 'https://api.orsf.sk/v1/search?q=sro&limit=20&offset=20'

Maximum offset is 1000 — for deeper paginations, narrow the search with filters (region, year, legal form). Cursor-based pagination is on the roadmap for larger datasets.

Versioning

URL-based versioning (/v1/...). Breaking changes will introduce/v2/... with a long overlap window. Field aliases (e.g., ico → nationalId) are added next to legacy keys and never remove the old form.

Subscribe to changes:

• Watch the GitHub repo
• OpenAPI spec is the source of truth — diff /v1/openapi.json over time

Status & SLA

Live status: status.orsf.sk. ORSF is a beta service — best-effort availability, no SLA. For production use cases requiring an SLA, contact us.

Issues, feature requests, abuse reports: [email protected].

Frequently asked questions

What is the ORSF API?

ORSF (Open Register of Slovak Companies) is a free, open REST API at api.orsf.sk for 1.25M+ Slovak companies and sole traders. It aggregates 14 state registers (RPO, ORSR, RÚZ, FS DPH and more) into one consistent JSON interface. Public read access requires no API key; person-level data and connection graphs require sign-in. License: CC-BY 4.0.

Is ORSF the same as ORSR?

No. ORSF (orsf.sk) is an independent open API; ORSR (orsr.sk) is the official Slovak Commercial Register run by the Ministry of Justice. ORSF uses ORSR as one of its 14 data sources but is not an official government register. Full disambiguation at /orsf-vs-orsr.

How do I get started with the ORSF API?

Three commands, no signup: curl https://api.orsf.sk/v1/companies/55609830 (company detail), curl https://api.orsf.sk/v1/search?q=poistovna (fulltext), curl https://api.orsf.sk/v1/stats/summary (aggregates). Full OpenAPI 3.1 spec at https://api.orsf.sk/v1/openapi.json.

Does ORSF have an MCP server for Claude / ChatGPT / Cursor?

Yes. Install with claude mcp add orsf -- npx -y @orsf/mcp-server. Works with Claude Code, Claude Desktop, Cursor, Continue, Windsurf, Zed and any MCP-compatible client. See /mcp for full setup.

How does ORSF compare to Finstat API?

Finstat API is paid (bundled with PREMIUM/ELITE/ULTIMATE subscriptions) and adds value-added services like ratings, monitoring, and exports. ORSF is free under CC-BY 4.0 and covers the same primary state registers (RPO, ORSR, RÚZ, FS DPH). ORSF additionally ships an MCP server for AI agents and a CLI, neither of which Finstat offers.

What are the rate limits?

Search and company detail: 60 req/min/IP. Graph endpoints: 20 req/min/IP. Force-refresh: 5 req/min/IP plus 60s per-IČO cooldown. For higher limits or bulk export, email [email protected].

Why is some data behind authentication?

Person-level data (directors, partners, beneficial owners) and connection graphs require sign-in to comply with GDPR Art. 6(1)(f) — preventing mass profiling of natural persons. Aggregating individually-public data increases privacy risk; the auth gate enables auditability while preserving legitimate due diligence and journalism use.

Glossary

IČO

Identifikačné číslo organizácie — 8-digit company national ID, used in SK and CZ.

DIČ

Daňové identifikačné číslo — tax identification number.

IČ DPH / VAT ID

VAT registration ID, prefixed with country code (e.g., SK2122034970).

RPO

Register právnických osôb — Register of Legal Entities (Statistical Office of SR).

RUZ

Register účtovných závierok — Register of Financial Statements (Ministry of Finance).

ORSR

Obchodný register SR — Slovak Commercial Register (Ministry of Justice).

ZRSR

Živnostenský register — Trade Register (Ministry of Interior).

NUTS

Nomenclature of Territorial Units for Statistics. ORSF uses NUTS-3 (regionCode) and LAU1 (districtCode).