API

API Documentation

FirmAPI provides a REST API for Slovak company data and extended enrichments including tax data, bank accounts, contacts, financial metrics, financial statements, insolvency, public procurement, and notifications via webhook or email.

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 combines core registers and supplemental enrichment sources 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
Tax and financial sources	Tax ID, VAT ID, VAT payer status, core financial metrics, financial statements	Continuously based on source availability
EU VIES	VAT ID validation	On demand (7-day cache)
Public registers and bulletins	Debtor lists, commercial bulletin, insolvency, public contracts and procurement	Continuously based on source availability

Stale Data & Background Refresh

FirmAPI returns the latest available data immediately and aims to keep data fetched from sources newer than 10 days. If ORSR data or supplemental source data is older, it automatically triggers a background refresh.

If ORSR details are older than 30 days or data fetched from supplemental sources is older than 10 days, the response will include staleness markers:

meta.stale: true — data is outdated
meta.retry_at — ISO 8601 timestamp when to poll again for fresh data
meta.stale_reason — for example orsr_data_outdated, enrichment_data_outdated, or orsr_and_enrichment_data_stale

Retry the same request after retry_at. Background refresh typically completes within 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

Query Parameters

scope

string

Comma-separated list of enrichment scopes to include. Omit for base data only (fastest).

Available scopes

By default, company endpoints return only core data (name, address, status). Use the scope parameter to include additional enrichment data. Each scope requires the corresponding feature on your plan.

tax, bank_accounts, contacts, financials, debtor_status, financial_statements, insolvency, commercial_bulletin, public_contracts, procurement

Example Request


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


curl -X GET "https://api.firmapi.sk/v1/company/ico/51636549?scope=tax,financials,debtor_status" \
     -H "Authorization: Bearer YOUR_API_KEY"


curl -X GET "https://api.firmapi.sk/v1/company/ico/51636549?scope=all" \
     -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)

GET /notifications

List your active and historical notification subscriptions.

POST /notifications

Create or update a change subscription for a specific company IČO. You can configure a webhook URL, an email target, or both.

Request Body

{
  "ico": "51636549",
  "webhook_url": "https://example.com/firmapi/webhook",
  "notification_email": "ops@example.com",
  "events": ["updated"]
}

DELETE /notifications/{ico}

Delete a subscription for the specified company IČO.

GET /notifications/{subscriptionId}/deliveries

Retrieve recent deliveries for a specific subscription, including channel, status, and retry attempts.

GET /notifications/history/{ico}

Get detected company change history for the specified IČO.

POST /notifications/test

Validate a webhook or email destination without creating a persistent subscription.

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

The tax section contains tax identifiers and VAT state: dic, ic_dph, is_vat_payer, vies_valid, 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.

Contacts, accounts, and financials

Optional enrichment sections based on plan: bank_accounts (IBAN, bank, published account), contacts (emails, phones, websites grouped by type), financials (year, revenue, profit, assets, employees_count).

Risk and compliance data

Advanced enrichments may include debtor_status, financial_statements (latest, available_years), insolvency, commercial_bulletin, public_contracts_summary, and procurement_summary.

Meta Fields

Response metadata: rpo_updated_at, orsr_synced_at, enriched_at, source (database, cache, or live), cached, stale, retry_at, and stale_reason.

Notifications: webhook and email

FirmAPI supports change notifications through webhook URLs and email. For each IČO you can configure either delivery channel or both, and manage them via API or dashboard.

Setup

Configure notifications in the dashboard or via POST /notifications. Webhook subscriptions receive a unique HMAC secret for signature verification.

Event Types

company.updated — Fired when existing company data is modified (e.g. address change, new shareholders, status update)
Delivery is sent to the configured webhook_url, notification_email, or both.

Payload Structure

Webhook payloads include the event type, timestamp, changed field with previous and new value, and a compact company snapshot. Email notifications carry the same event meaning, but are delivered as readable messages without HMAC headers.

{
  "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 a webhook endpoint returns a non-2xx status code, FirmAPI retries delivery with exponential backoff. Delivery history is available via <code>GET /notifications/{subscriptionId}/deliveries</code>. Email notifications are logged in the same delivery history with channel <code>email</code>.

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