API

API Documentation

FirmAPI provides a REST API to access Slovak company data aggregated from multiple official registers (RPO, ORSR, ZRSR) with automatic enrichment from tax authorities and EU VIES.

Authentication

All API requests require authentication using an API key. You can create API keys in your dashboard.

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Or use the X-API-Key header:

X-API-Key: YOUR_API_KEY

Base URL

https://api.firmapi.sk/v1

Data Sources

FirmAPI aggregates data from multiple Slovak registers into a single response:

Source	Data	Update Frequency
RPO (Register of Legal Entities)	Name, registration number, address, legal form, status	Daily
ORSR (Commercial Register)	Shareholders, statutory bodies, business activities, registered capital	On demand / monthly
RegisterUZ / Financial Administration	Tax ID, VAT ID, VAT payer status	Daily (on change)
EU VIES	VAT ID validation	On demand (7-day cache)

Stale Data & Background Refresh

For companies in the commercial register (ORSR), detailed data (shareholders, statutory bodies, business activities) is periodically refreshed from ORSR.sk.

If the ORSR data is older than 30 days, the API returns the existing (stale) data immediately and queues a background refresh. The response will include:

meta.stale: true — data is outdated
meta.retry_at — ISO 8601 timestamp when to poll again for fresh data
meta.stale_reason — either orsr_data_outdated or orsr_data_not_available

Simply retry the same request after retry_at to get fresh data. The background refresh typically completes in 10-15 seconds.

{
  "data": { ... },
  "meta": {
    "rpo_updated_at": "2026-02-05T06:00:00Z",
    "orsr_synced_at": "2025-12-01T14:30:00Z",
    "source": "database",
    "stale": true,
    "retry_at": "2026-02-05T12:00:15Z",
    "stale_reason": "orsr_data_outdated"
  }
}

Endpoints

GET /company/ico/{ico}

Get company details by IČO (registration number).

Parameters

ico

string

8-digit company registration number

Example Request

curl -X GET "https://api.firmapi.sk/v1/company/ico/51636549" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "ico": "51636549",
    "name": "Version Two s. r. o.",
    "legal_form": "Spoločnosť s ručením obmedzeným",
    "legal_form_code": "112",
    "address": {
      "street": "Hlavná 1",
      "city": "Bratislava",
      "postal_code": "81101",
      "country": "Slovensko"
    },
    "established_date": "2018-05-15",
    "terminated_date": null,
    "source_register": "Obchodný register",
    "status": "active",
    "orsr_id": "427482",
    "registration_date": "2018-05-15",
    "business_activities": "Počítačové služby...",
    "registered_capital": "5 000 EUR",
    "shareholders": [
      {"name": "John Doe", "address": "Bratislava", "share_amount": "5000 EUR", "share_percentage": "100%"}
    ],
    "statutory_body": [
      {"name": "John Doe", "role": "konateľ", "address": "Bratislava"}
    ]
  },
  "meta": {
    "rpo_updated_at": "2026-02-05T06:00:00Z",
    "orsr_synced_at": "2026-01-20T14:30:00Z",
    "source": "database"
  }
}

GET /search/autocomplete

Search companies by name or IČO with autocomplete. Returns Select2-compatible format.

Query Parameters

q	string	Search query (min 2 characters)
limit	integer	Max results (default: 10, max: 20)

Example Response

{
  "results": [
    {"id": "51636549", "text": "Version Two s. r. o.", "ico": "51636549", "city": "Bratislava"},
    {"id": "12345678", "text": "Version s.r.o.", "ico": "12345678", "city": "Košice"}
  ],
  "pagination": {"more": false}
}

GET /company/id/{orsr_id}

Get company details by ORSR internal ID.

Example Request

curl -X GET "https://api.firmapi.sk/v1/company/id/427482" \
     -H "Authorization: Bearer YOUR_API_KEY"

GET /company/{id}

Get company details by internal database ID.

Example Request

curl -X GET "https://api.firmapi.sk/v1/company/12345" \
     -H "Authorization: Bearer YOUR_API_KEY"

GET /search/name

Search companies by name with pagination.

Query Parameters

q	string	Company name (min 3 characters)
exact	integer	Exact match (0 or 1, default: 0)
limit	integer	Max results (default: 10, max: 100)
offset	integer	Pagination offset (default: 0)

GET /search/ico

Search companies by partial IČO number.

Query Parameters

q	string	Partial IČO
limit	integer	Max results (default: 10, max: 100)

GET /search/advanced

Multi-field search with various filters.

Query Parameters

name	string	Company name
city	string	City name
legal_form	string	Legal form

POST /batch/ico Requires Starter+ plan

Batch lookup of multiple companies by IČO. Requires Starter plan or higher.

Request Body

{
  "icos": ["51636549", "12345678", "87654321"]
}

Example Response

{
  "data": {
    "51636549": {"found": true, "data": {...}},
    "12345678": {"found": true, "data": {...}},
    "87654321": {"found": false, "data": null}
  },
  "meta": {
    "total": 3,
    "found": 2,
    "not_found": 1
  }
}

POST /batch/names Requires Starter+ plan

Batch lookup of multiple companies by name. Requires Starter plan or higher.

Request Body

{
  "names": ["Version Two s. r. o.", "Example Company"]
}

GET /account/usage

Get current period usage statistics.

GET /account/quota

Get remaining quota for current billing period.

GET /account/history

Get usage history for the specified period.

Query Parameters

days

integer

Number of days to retrieve (default: 30, max: 365)

Response Format & Data Model

Company endpoints return a JSON object with data and meta fields. The data object contains all available company information grouped into the following categories.

Basic Information

Core company data from RPO: ico, name, legal_form, legal_form_code, address (street, city, postal_code, country), status (active, terminated, deleted), established_date, terminated_date, source_register.

Tax Information

Tax identifiers and VAT status: dic (Tax ID), ic_dph (VAT ID), is_vat_payer, vies_valid (EU VIES validation result), vies_verified_at.

ORSR Details

Detailed data from the commercial register (only for ORSR companies): orsr_id, shareholders (name, address, share_amount, share_percentage, is_company, ico), statutory_body (name, role, address, acting_method), business_activities, registered_capital, registration_date.

Meta Fields

Response metadata: rpo_updated_at (last RPO sync), orsr_synced_at (last ORSR fetch), source (database or cache), stale (boolean, whether ORSR data is outdated), retry_at (when to poll for fresh data), stale_reason.

Webhooks

Webhooks allow you to receive real-time notifications when company data changes in FirmAPI. Instead of polling the API, you can configure a URL to receive HTTP POST requests whenever relevant events occur.

Setup

Configure your webhook endpoint in the dashboard. Each subscription receives a unique HMAC secret used for signature verification.

Event Types

company.updated — Fired when existing company data is modified (e.g. address change, new shareholders, status update)
company.created — Fired when a new company is added to the database

Payload Structure

Each webhook request contains a JSON payload with the event type, timestamp, the changed field with its old and new values, and current company data including tax information.

{
  "event": "company.updated",
  "timestamp": "2026-02-05T12:00:00Z",
  "data": {
    "ico": "51636549",
    "change_type": "updated",
    "field": "address",
    "old_value": "Hlavná 1, 81101 Bratislava",
    "new_value": "Mlynské nivy 5, 82109 Bratislava",
    "detected_at": "2026-02-05T06:15:00Z",
    "company": {
      "name": "Version Two s. r. o.",
      "legal_form": "Spoločnosť s ručením obmedzeným",
      "city": "Bratislava",
      "status": "active"
    },
    "tax_info": {
      "dic": "2120776680",
      "ic_dph": "SK2120776680",
      "is_vat_payer": true
    }
  }
}

Headers

X-Webhook-Signature — HMAC-SHA256 signature of the request body using your webhook secret
X-Webhook-Event — Event type (e.g. company.updated)
X-Webhook-Delivery-Id — Unique delivery identifier for idempotency

Signature Verification

Every webhook request is signed using HMAC-SHA256. Verify the signature to ensure the request is authentic and has not been tampered with.

// PHP verification example
$signature = $request->header('X-Webhook-Signature');
$payload = $request->getContent();
$expected = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // Signature is valid
}

Retry Behavior

If your endpoint returns a non-2xx status code, FirmAPI will retry delivery with exponential backoff: after 5 minutes, 30 minutes, 2 hours, and 12 hours. After 10 consecutive failures, the webhook subscription is automatically disabled.

Rate Limits

Rate limits depend on your subscription tier. The following headers are included in all responses:

X-RateLimit-Limit-Minute — Requests allowed per minute
X-RateLimit-Remaining-Minute — Requests remaining this minute
X-RateLimit-Limit-Daily — Requests allowed per day
X-RateLimit-Remaining-Daily — Requests remaining today

Errors

All errors return a JSON object with error and message fields.

Status Code	Error	Description
401	unauthorized	Invalid or missing API key
403	forbidden	Feature not available on your plan
404	not_found	Company not found
422	validation_error	Invalid request parameters
429	rate_limit_exceeded	Too many requests
503	service_unavailable	Service temporarily unavailable