Quickstart

1. Create an account at app.maticna.si/sign-up. The free Hobby plan includes 100 units a month (at most 20 a day), no card required.

2. Create a key on the Keys page. There is one kind of secret key, mk_…, and it always returns real data; there is no separate test environment. The key is shown only once; store it in an environment variable:

   export MATICNA_KEY="mk_…"

3. Call the API. The call returns a real record from the FURS register and uses 1 unit of the Hobby plan. To just try requests, use the API tester in the dashboard: it uses no units.

   curl

   curl https://api.maticna.si/v1/entities/80267432 \
     -H "Authorization: Bearer $MATICNA_KEY"

   JavaScript

   const res = await fetch('https://api.maticna.si/v1/entities/80267432', {
     headers: { Authorization: `Bearer ${process.env.MATICNA_KEY}` },
   });
   if (!res.ok) {
     const problem = await res.json(); // application/problem+json
     throw new Error(`${problem.code}: ${problem.detail ?? problem.title}`);
   }
   const entity = await res.json();
   console.log(entity.name, entity.vat.registered);

   PHP

   <?php
   $ch = curl_init('https://api.maticna.si/v1/entities/80267432');
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MATICNA_KEY')],
   ]);
   $entity = json_decode(curl_exec($ch), true);
   $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
   echo $status === 200 ? $entity['name'] : $entity['code'];

   Python

   import os, requests
   
   r = requests.get(
       "https://api.maticna.si/v1/entities/80267432",
       headers={"Authorization": f"Bearer {os.environ['MATICNA_KEY']}"},
       timeout=5,
   )
   if r.ok:
       entity = r.json()
       print(entity["name"], entity["vat"]["registered"])
   else:
       print(r.json()["code"])

   C#

   using System.Net.Http.Headers;
   using System.Text.Json;
   
   using var http = new HttpClient { BaseAddress = new Uri("https://api.maticna.si/v1/") };
   http.DefaultRequestHeaders.Authorization =
       new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MATICNA_KEY"));
   
   var res = await http.GetAsync("entities/80267432");
   using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
   Console.WriteLine(res.IsSuccessStatusCode
       ? doc.RootElement.GetProperty("name").GetString()
       : doc.RootElement.GetProperty("code").GetString());

4. Read the response. You get an entity object with the address, activity, VAT status and source:

   {
     "object": "entity",
     "tax_number": "80267432",
     "vat_id": "SI80267432",
     "type": "legal_entity",
     "status": "active",
     "name": "PETROL, SLOVENSKA ENERGETSKA DRUŽBA, D.D., LJUBLJANA",
     "legal_form": "d.d.",
     "vat": { "registered": true, "registered_on": "1999-07-01", "scope_code": null, "group_id": null, "source": "furs_po" },
     "source": { "dataset": "furs_po", "as_of": "2026-10-19", "attribution": "Vir: FURS" }
   }

Next steps

• Name search and autocomplete: Search.

• Bulk checks (Starter plan and up): POST /v1/entities/lookup with up to 100 IDs:

  curl https://api.maticna.si/v1/entities/lookup \
    -H "Authorization: Bearer $MATICNA_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{"ids": ["80267432", "SI80267432", "5025796000"]}'

• Handle errors by code, not by text: Errors.

• Before going to production, read Rate limits and quotas and Billable units.