Skip to content
maticna.siDocs

maticna.si API

maticna.si is a REST API for every Slovenian taxpayer on the FURS lists: legal entities, sole proprietors (s.p.) and other natural persons carrying out an activity, with VAT status, VAT ID revocations and VAT groups. We refresh the data the same day FURS publishes it.

curl https://api.maticna.si/v1/entities/80267432 \
  -H "Authorization: Bearer $MATICNA_KEY"
QuickstartA key and your first call in two minutes: curl, JS, PHP, Python, C#.
API referenceEvery endpoint from openapi.json, with request and response examples.
The entity objectField by field: type, status, VAT, revocations, registrations.
ErrorsRFC 9457 problem+json and a page for every code.
MCP serverThe register in Claude, Cursor, VS Code and agents. Same keys and units as REST.

Conventions

Section titled “Conventions”
  • Base URL: https://api.maticna.si/v1. HTTPS only.
  • snake_case JSON with an object discriminator (entity, list, vat_check, …). New enum values can appear at any time; your code must tolerate them.
  • Headers on every response: X-Request-Id, X-Data-As-Of (FURS source date), X-Data-Version.
  • Source attribution: source.attribution or meta.attribution is always Vir: FURS (“Source: FURS”).
  • Versioning: only backward-compatible (additive) changes within /v1. Breaking changes go to /v2 with at least 12 months of overlap and the Deprecation/Sunset headers.
  • Language: field names and error codes are English; title and detail follow Accept-Language: sl|en.

Endpoints

Section titled “Endpoints”
Method and path Purpose Units
GET /v1/entities/{tax_number} Taxpayer by tax number (also accepts SI…) 1
GET /v1/entities/by-registration-number/{reg} By registration number (7 or 10 digits), returns a list 1
GET /v1/entities/by-vat/{vat_id} By VAT ID 1
POST /v1/entities/lookup Up to 100 mixed IDs in one call (Starter and up) 1 per distinct ID
GET /v1/entities?q=… Search and filtering 1 per page
GET /v1/autocomplete?q=… Autocomplete (publishable keys allowed) 0.25
GET /v1/vat/validate/{vat_id} VAT ID validation 1
GET /v1/tax-number/validate/{n} Mod-11 check and presence in the register 1
GET /v1/reference/{activity-codes,tax-offices,legal-forms,postal-codes} Code lists 0
GET /v1/meta/status Data freshness per list 0
GET /v1/usage Usage and quota 0
GET /v1/openapi.json Specification 0

Change tracking (Growth and up): GET /v1/changes and GET /v1/entities/{tax}/history, see Changes and history. Monitors and signed webhooks (Starter and up): Monitors, Webhooks.

Source: FURS · unofficial source, not an official extract · Terms · Privacy · maticna.si