# maticna.si > REST API over the Slovenian FURS taxpayer lists: every Slovenian company and sole proprietor (s.p.) by tax number, VAT ID or registration number (matična), with VAT status, VAT revocations and fuzzy name search. Refreshed daily (same-day, not real-time). Unofficial source; attribution "Vir: FURS". - API base URL: https://api.maticna.si/v1 - OpenAPI: https://maticna.si/openapi.json (also https://api.maticna.si/v1/openapi.json) - Auth: `Authorization: Bearer mk_...` (secret, server-side only; legacy `mk_live_...` also works; `mk_test_...` keys were discontinued and return 401 `test_keys_removed`) or `mk_pub_...` (publishable, autocomplete and VAT validation only). Never put keys in query strings: the key is revoked. - Responses: snake_case JSON with an `object` discriminator. Errors are application/problem+json with a stable `code`. - Hobby plan (free): 100 units/month, at most 20 a day; paid plans below. Sign up: https://app.maticna.si/sign-up ## Docs - [Quickstart](https://maticna.si/docs/quickstart/): First request with curl, JavaScript, PHP, Python and C#. - [Authentication & keys](https://maticna.si/docs/authentication/): Secret (mk_…; legacy mk_live_… still works) vs publishable (mk_pub_) keys, Bearer header, never in query strings. No test keys or sandbox: every key returns real data. - [MCP server](https://maticna.si/docs/mcp/): Remote MCP server for Claude, Cursor, VS Code and agent APIs; same keys, quota and units as REST. - [Search](https://maticna.si/docs/search/): Name search with diacritic folding (č/š/ž/ć/đ), legal-form handling, filters, autocomplete. - [Pagination & cursors](https://maticna.si/docs/pagination/): Opaque signed cursors, depth caps, 409 cursor_expired after a data refresh. - [Rate limits, quotas & headers](https://maticna.si/docs/rate-limits/): RateLimit / RateLimit-Policy (draft-11), X-Quota-*, Retry-After, ETag and 304. - [Billable units](https://maticna.si/docs/billable-units/): Exactly which responses cost units (404 on a well-formed ID costs 1; 4xx/5xx cost 0). - [Changes & history](https://maticna.si/docs/changes/): Polling change feed (/v1/changes, cursor via since) and per-taxpayer history; Growth plan and up, 1 unit per page. - [Financial statements (AJPES)](https://maticna.si/docs/financials/): Annual-report key figures of companies from AJPES (CC BY 4.0, keep the attribution), provenance per statement, plan access, never for s.p.; 1 unit, include=financials_latest +1. - [Monitors](https://maticna.si/docs/monitors/): Watchlist of tax numbers (/v1/monitors, bulk up to 1,000); slots per plan, 0 units; e-mail alerts (instant per data refresh or weekly digest) on every plan. - [Webhooks](https://maticna.si/docs/webhooks/): Standard Webhooks signed events for monitored taxpayers, retries ~3 days, Node.js signature check; Starter plan and up. - [Errors](https://maticna.si/docs/errors/): RFC 9457 problem+json; one page per code. - [Entity object](https://maticna.si/docs/entity/): Field-by-field reference for the taxpayer resource. - [Data & FURS quirks](https://maticna.si/docs/data/): Which FURS lists we merge, VAT for s.p. from FO, scope codes P/O/S/Č, matična suffixes, freshness. - [Changelog](https://maticna.si/docs/changelog/): API changes and deprecation policy. - [API reference](https://maticna.si/docs/api/): Interactive OpenAPI reference. ## Endpoints - `GET /v1/entities/{tax_number}`: taxpayer by 8-digit tax number (accepts SI prefix). 1 unit. - `GET /v1/entities/by-registration-number/{reg}`: by 7- or 10-digit matična; returns a list. 1 unit. - `GET /v1/entities/by-vat/{vat_id}`: by SI VAT ID; 404 `not_vat_registered` if the entity exists without VAT. 1 unit. - `POST /v1/entities/lookup`: up to 100 mixed IDs, results in input order (Starter+). 1 unit per distinct well-formed ID. - `GET /v1/entities?q=...`: search and filtered listing; limit ≤ 50; cursor pagination. 1 unit per page. - `GET /v1/autocomplete?q=...`: lean projection, limit ≤ 10. 0.25 units. - `GET /v1/vat/validate/{vat_id}`, `GET /v1/tax-number/validate/{n}`: validation. 1 unit. - `GET /v1/reference/{activity-codes,tax-offices,legal-forms,postal-codes}`, `GET /v1/meta/status`, `GET /v1/usage`: free. - `GET /v1/entities/{tax_number}/financials?years=5`: AJPES annual-report figures (CC BY 4.0, attribution required; d.o.o., d.d., cooperatives; s.p. → `coverage.status: not_covered`, never data). Standalone `figures` per year plus the group's `consolidated` figures where the ESEF annual report has them (large audited companies, 2024 on); `documents` lists reports AJPES publishes only as files (PDF/ZIP) with a link to AJPES JOLP (`coverage.status: documents_only` when there are no figures). Years and figures by plan, `include=items` raw line items on Growth+. 1 unit. `GET /v1/entities/{tax_number}?include=financials_latest` adds the newest summary: +1 unit when returned. - `GET /v1/changes?since=`: change feed, ≤ 1,000 per page (Growth+). 1 unit per page. `GET /v1/entities/{tax_number}/history`: changes of one taxpayer (Growth+). 1 unit. - `POST/GET /v1/monitors`, `DELETE /v1/monitors/{tax_number}`, `POST /v1/monitors/bulk`: watchlist (slots per plan). `CRUD /v1/webhook-endpoints` (+ `/{id}/test`, `/{id}/roll-secret` with a grace period): signed webhooks (Starter+). Free. ## MCP server - Endpoint: https://mcp.maticna.si/mcp (Streamable HTTP, POST, JSON responses). Auth: `Authorization: Bearer mk_...` (secret key; publishable keys rejected; no sandbox, always real data). Billed exactly like REST, same quota. - `search_entities`: Find companies and s.p. by name, or filter by city, postcode, activity, VAT status or legal form. Up to 20 per page, cursor. 1 unit(s). - `get_entity`: Full record by tax number, VAT ID (SI…) or registration number (7 or 10 digits). 1 unit(s). - `lookup_entities`: Up to 50 mixed identifiers in one call. Starter plan and up. 1 per distinct ID unit(s). - `validate_vat_id`: Whether SIxxxxxxxx is a valid, registered Slovenian VAT ID as of the data date. 1 unit(s). - `validate_tax_number`: mod-11 checksum and presence in the FURS lists. 1 unit(s). - `list_reference_codes`: Reference codes: SKD activities, legal forms, tax offices, postal codes. 0 unit(s). - `get_usage`: Plan, units used and remaining, reset time, the key's usage and monthly cap. 0 unit(s). - `list_changes`: Changes in the FURS lists since a date or cursor (new entities, deactivations, VAT …), filter by type. Up to 50 per page. Growth plan and up. 1 unit(s). - `get_entity_history`: Change history of one tax number (all registrations), cursor. Growth plan and up. 1 unit(s). - `list_monitors`: The organisation’s watched tax numbers and watch slots used. 0 unit(s). - `get_financials`: Financial statements from AJPES annual reports (revenue, net profit, employees, assets, equity …) by tax number or matična, with source and CC BY 4.0 licence. Never for s.p. 1 unit(s). ## Error codes - [bad_request](https://maticna.si/docs/errors/bad_request/) (400): Bad request - [key_in_query_forbidden](https://maticna.si/docs/errors/key_in_query_forbidden/) (400): API key in query string is forbidden - [missing_api_key](https://maticna.si/docs/errors/missing_api_key/) (401): Missing API key - [invalid_api_key](https://maticna.si/docs/errors/invalid_api_key/) (401): Invalid API key - [key_revoked](https://maticna.si/docs/errors/key_revoked/) (401): API key revoked - [key_expired](https://maticna.si/docs/errors/key_expired/) (401): API key expired - [test_keys_removed](https://maticna.si/docs/errors/test_keys_removed/) (401): Test keys were discontinued - [payment_required](https://maticna.si/docs/errors/payment_required/) (402): Payment required - [insufficient_scope](https://maticna.si/docs/errors/insufficient_scope/) (403): Insufficient scope - [plan_upgrade_required](https://maticna.si/docs/errors/plan_upgrade_required/) (403): Plan upgrade required - [origin_not_allowed](https://maticna.si/docs/errors/origin_not_allowed/) (403): Origin not allowed - [monitor_limit_reached](https://maticna.si/docs/errors/monitor_limit_reached/) (403): Monitor limit reached - [webhook_endpoint_limit_reached](https://maticna.si/docs/errors/webhook_endpoint_limit_reached/) (403): Webhook endpoint limit reached - [ip_not_allowed](https://maticna.si/docs/errors/ip_not_allowed/) (403): IP address not allowed - [not_found](https://maticna.si/docs/errors/not_found/) (404): Not found - [not_vat_registered](https://maticna.si/docs/errors/not_vat_registered/) (404): Not VAT registered - [cursor_expired](https://maticna.si/docs/errors/cursor_expired/) (409): Cursor expired - [idempotency_conflict](https://maticna.si/docs/errors/idempotency_conflict/) (409): Idempotency key reused with a different request - [invalid_tax_number](https://maticna.si/docs/errors/invalid_tax_number/) (422): Invalid tax number - [invalid_vat_id](https://maticna.si/docs/errors/invalid_vat_id/) (422): Invalid VAT ID - [invalid_registration_number](https://maticna.si/docs/errors/invalid_registration_number/) (422): Invalid registration number - [query_too_short](https://maticna.si/docs/errors/query_too_short/) (422): Query too short - [invalid_webhook_url](https://maticna.si/docs/errors/invalid_webhook_url/) (422): Invalid webhook URL - [rate_limited](https://maticna.si/docs/errors/rate_limited/) (429): Rate limited - [quota_exceeded](https://maticna.si/docs/errors/quota_exceeded/) (429): Quota exceeded - [natural_person_cap_exceeded](https://maticna.si/docs/errors/natural_person_cap_exceeded/) (429): Daily natural-person lookup cap exceeded - [internal_error](https://maticna.si/docs/errors/internal_error/) (500): Internal error - [upstream_stale](https://maticna.si/docs/errors/upstream_stale/) (503): Data temporarily stale - [search_timeout](https://maticna.si/docs/errors/search_timeout/) (503): Search timed out ## Plans (EUR/month, excl. VAT) - Hobby (code `free`): €0; 100 units/month (max 20/day); 1 rps; 1 secret key; no watched companies (monitors) or e-mail change alerts; 20 sole traders/day; 1 team member; AJPES financials not included. - Starter (code `starter`): €15/month or €150/year; 2,500 units/month; 5 rps; 3 secret keys; 50 watched companies; 200 sole traders/day; 3 team members; AJPES financials last 3 years, summary; publishable keys, webhooks, bulk lookup; opt-in overage €8/1,000 units; top-up +2,500 units for €12. - Growth (code `growth`): €39/month or €390/year; 10,000 units/month; 15 rps; 10 secret keys; 500 watched companies; 1,000 sole traders/day; 10 team members; AJPES financials all years, raw line items; publishable keys, webhooks, bulk lookup, change feed + history, DPA; opt-in overage €5/1,000 units; top-up +10,000 units for €39. - Custom (code `custom`): price by agreement (annual contract, invoice); negotiated units; negotiated burst; unlimited secret keys; negotiated watched companies; negotiated sole traders/day; unlimited team members; AJPES financials all years, raw line items; publishable keys, webhooks, bulk lookup, change feed + history, DPA, SLA. - Every plan: MCP server, dashboard API tester. Watched companies (monitors) with e-mail change alerts and AJPES financials start at Starter. ## Optional - [Privacy notice for sole proprietors](https://maticna.si/zasebnost/podjetniki/) - [Terms of use](https://maticna.si/pogoji-uporabe/)