Table of Contents

Getting Started
Companies API
Documents API
Compliance & Sanctions
Edicts (Edikte)

API Documentation

A REST API for modern developers. Complete reference for the firmafind API endpoints. Integrate Austrian company data seamlessly into your application.

Getting Started
Authentication and basic API usage

Base URL

https://firmafind.at

Authentication

All API requests require an API key in the x-api-key Header:

x-api-key: YOUR_API_KEY

Example Request

curl -X GET "https://firmafind.at/api/search?name=example" \
  -H "x-api-key: YOUR_API_KEY"
OpenAPI Specification
Import the entire firmafind API into your favorite client in seconds

The full API is described in a single OpenAPI 3.0 document. Import it into Postman, Insomnia, Apifox, Bruno, or swagger.io to get an interactive explorer, typed request templates, and one-click client code generation.

Spec URL

https://firmafind.at/openapi.yaml

Quick start

Postman / Insomnia / Apifox / Bruno

Import → From URL → paste the spec URL above. All endpoints, parameters, and auth are preconfigured.

Generate a typed client

npx openapi-typescript-codegen \
  --input https://firmafind.at/openapi.yaml \
  --output ./firmafind-client

Browse live in swagger.io / Redoc

Paste the spec URL at editor.swagger.io for instant interactive docs.

Rate Limiting
Understanding API rate limiting and quota windows

To ensure platform stability, the FirmaFind API employs two layers of rate limits: a Daily Quota (resetting at midnight ) and a Burst Limit (sliding 60-second window to prevent sudden spikes in traffic).

Rate Limit Tiers

Tier / User StatusDaily QuotaBurst LimitAuthentication
Anonymous30 requests / day5 requests / minNo Key (IP-based)
Free User50 requests / day120 requests / minAPI Key Required
Trial User500 requests / day30 requests / minAPI Key Required
SubscriberUnlimited120 requests / minAPI Key Required

When Exceeded

If you exceed either the daily quota or the 60-second burst window, the API returns a HTTP 429 Too Many Requests response code. The response contains standard rate-limiting headers:

HeaderTypeDescription
X-RateLimit-LimitintegerYour tier's maximum daily request allowance
X-RateLimit-RemainingintegerRemaining requests available within the current daily window
X-RateLimit-ResettimestampUnix epoch timestamp (seconds) when the daily quota resets
Retry-AfterintegerReturned only on 429 responses. The number of seconds you must wait before retrying.
X-Usage-PolicyurlLink to the Acceptable Use Policy

Best Practices & Tips

  • Check headers to monitor usage and proactively pace requests.
  • Handle 429 status codes programmatically and implement exponential backoff.
  • Cache search results locally (data is updated daily) to conserve credits and improve response times.
  • Sandbox endpoints (/api/sandbox/*) are free (0 credit cost) but have a fixed limit of 5 requests/minute per user.
Endpoint Overview
All available API endpoints at a glance
GET/api/search/publicNo API KeyPublic Company Search
GET/api/sandbox/searchSandboxDeveloper Sandbox (Fictional Data)
GET/api/searchSearch Companies
GET/api/company/:fnrGet Company Details
GET/api/company/changesGet Company Changes (Beta)
GET/api/documentsList Documents
GET/api/documents/:keyDownload Document
GET/api/sanctions/searchSearch EU SanctionsNew
GET/api/sanctions/filtersSanctions Metadata & FiltersNew
GET/api/edikteSearch EdikteBeta
GET/api/edikte/:type/:idGet Edikt DetailsBeta

Endpoints in Detail

GET/api/company/:fnr
Get Company Details
Retrieves detailed company register information for a specific company, including address, management, and company register transactions.

URL Parameters

ParameterTypeRequiredDescription
fnrstringJaCompany Register Number (z.B. 579180k)

Example Code

curl -X GET "https://firmafind.at/api/company/579180k" \
  -H "x-api-key: YOUR_API_KEY"

Response Schema

FieldTypeDescription
fnrstringCompany Register Number
euidstringEuropean Business Identifier
companyNamestringOfficial company name
isActivebooleanStatus ob Firma aktiv ist
legalFormstringFull legal form description
addressobjectAddress data (street, postal code, city, seat)
managementarrayList of managing directors with roles
transactionsarrayFirmenbuch transaction history
foundationDatestringFoundation or first registration date (YYYY-MM-DD)

JSON Example

{
  "success": true,
  "data": {
    "fnr": "579180 k",
    "euid": "ATBRA.579180-000",
    "companyName": "Chladek & Sons GmbH",
    "isActive": true,
    "legalForm": "Gesellschaft mit beschränkter Haftung",
    "foundationDate": "2022-04-13",
    "address": {
      "street": "Czerninplatz",
      "houseNumber": 4,
      "postalCode": 1020,
      "city": "Wien",
      "seat": "Wien"
    },
    "management": [
      {
        "name": "Dipl.-Ing. Josef Gottfried Chladek",
        "role": "GESCHÄFTSFÜHRER/IN (handelsrechtlich)",
        "position": "vertritt seit 13.04.2022 selbständig",
        "since": "13.04.2022"
      }
    ],
    "transactions": [
      {
        "id": "1",
        "description": "Antrag auf Neueintragung einer Firma eingelangt am 11.04.2022",
        "date": "2022-04-13",
        "type": "Handelsgericht Wien"
      }
    ]
  },
  "meta": {
    "cost": 0
  }
}
GET/api/company/changesBeta
Get Company Changes
Retrieves changes (Veränderungen) to company registers registered in the Austrian Firmenbuch for a specific date range. Includes support for filtering by court, legal form, and type of change.

Query Parameters

ParameterTypeRequiredDescription
fromstringJaStart date in YYYY-MM-DD format (falls back to von). The date range between from and to cannot exceed 7 days.
tostringJaEnd date in YYYY-MM-DD format (falls back to bis). The date range between from and to cannot exceed 7 days.
changeTypestringNeinFilter by the type of change. Supported values:
  • new: Maps to Neueintragung (company creation/registration)
  • change: Maps to Änderung (company detail updates)
  • delete: Maps to Löschung (company deletion/removal)
courtstringNeinCourt code filter (e.g. 007 for Landesgericht Linz). Falls back to gericht.
legalFormstringNeinLegal form code filter (e.g. AG, GMBH). Falls back to rechtsform.
industrystringNeinFilter by industry using rule-based classification of company names. Supported values:
  • it: IT / Software / Tech
  • gastro: Gastronomy & Tourism
  • bau: Construction & Craftsmanship
  • immo: Real Estate
  • consulting: Consulting & Management

Example Code

curl -X GET "https://firmafind.at/api/company/changes?from=2026-07-01&to=2026-07-03&changeType=new" \
  -H "x-api-key: YOUR_API_KEY"

Response Schema

FieldTypeDescription
fnrstringCompany Register Number (Firmenbuchnummer, z.B. 875 m)
vnrnumberExecution Number (Vollzugsnummer, z.B. 7). Indicates the version sequence of changes.
datestringExecution Date (Vollzugsdatum, YYYY-MM-DD)
changeTypestringType of change (Art der Veränderung): new (Neueintragung), change (Änderung), or delete (Löschung).

Example Response

{
  "data": [
    {
      "fnr": "875 m",
      "vnr": 7,
      "date": "2026-07-03",
      "changeType": "new",
      "companyName": "Müller Holzbau GmbH",
      "industry": "bau"
    },
    {
      "fnr": "1769 b",
      "vnr": 34,
      "date": "2026-07-02",
      "changeType": "change",
      "companyName": "Went IT-Service GmbH",
      "industry": "it"
    }
  ],
  "meta": {
    "count": 2
  }
}
GET/api/documents
List Documents
Retrieves a list of all available documents (annual financial statements, balance sheets) for a specific company. Documents are available both as PDF and XML.

Query Parameters

ParameterTypeRequiredDescription
fnrstringJaCompany Register Number of the company

Example Code

curl -X GET "https://firmafind.at/api/documents?fnr=579180k" \
  -H "x-api-key: YOUR_API_KEY"

Response Schema

FieldTypeDescription
keystringUnique document key for download
fnrstringCompany Register Number
dokumentartobjectDocument type with code and description
contentTypeestringMIME type (application/pdf or application/xml)
stichtagstringBalance sheet date (YYYY-MM-DD)

JSON Example

{
  "success": true,
  "data": [
    {
      "key": "579180_0070752319041_000___000_30_29893872_PDF",
      "fnr": "579180 k",
      "az": "007 075 Fr 19041/23 b",
      "dokumentart": {
        "code": 48,
        "text": "Annual Financial Statement"
      },
      "contentTypee": "application/pdf",
      "dateiendung": "pdf",
      "groesse": 118285,
      "stichtag": "2022-12-31",
      "gkl": "W",
      "vnr": 2,
      "eingereicht": "2023-05-09"
    },
    {
      "key": "579180_0070752521339_000___000_30_35697663_XML",
      "fnr": "579180 k",
      "az": "007 075 Fr 21339/25 z",
      "dokumentart": {
        "code": 48,
        "text": "Annual Financial Statement"
      },
      "contentTypee": "application/xml",
      "dateiendung": "xml",
      "groesse": 4226,
      "stichtag": "2024-12-31",
      "gkl": "W",
      "vnr": 4,
      "eingereicht": "2025-06-04"
    }
  ],
  "meta": {
    "count": 2,
    "filters": {
      "fnr": "579180k"
    }
  }
}
GET/api/documents/:key
Fetch Document & Annual Report
Retrieves a specific document. Electronically filed annual financial statements (Jahresabschluss XML) are automatically parsed into a clean, structured REST JSON object (annualReport with Balance Sheet, Income Statement, Notes, and KPIs). PDFs and other documents return standardized metadata along with the Base64 file payload.

URL Parameters

ParameterTypeRequiredDescription
keystringYesUnique document key from the document list

Example Code

The following examples show how to retrieve the structured document or save the file.

curl -X GET "https://firmafind.at/api/documents/579180_0070752521339_000___000_30_35697663_XML" \
  -H "x-api-key: YOUR_API_KEY"

Response Schema

FieldTypeDescription
typestringDocument classification (annual_report, pdf_document, xml_document)
metadataobjectStandardized document metadata (FNR, Aktenzeichen, dates, court, size)
annualReportobject | nullStructured annual financial statement (JAb 3.32) with Balance Sheet, Income Statement, Notes, and KPIs
rawobjectFile details and Base64-encoded payload

JSON Example (Jahresabschluss)

{
  "data": {
    "type": "annual_report",
    "metadata": {
      "key": "579180_0070752521339_000___000_30_35697663_XML",
      "urkid": "35697663",
      "fnr": "579180k",
      "az": "070 Fr 7525/21 y",
      "documentType": {
        "code": "48",
        "text": "Jahresabschluss"
      },
      "documentDate": "2024-06-30",
      "referenceDate": "2023-12-31"
    },
    "annualReport": {
      "meta": {
        "jabVersion": "3.32",
        "reportingPeriodStart": "2023-01-01",
        "reportingPeriodEnd": "2023-12-31",
        "currency": "EUR",
        "source": "firmenbuch",
        "fileId": "579180_0070752521339_000___000_30_35697663_XML"
      },
      "company": {
        "firmenbuchNumber": "579180k",
        "name": "Muster GmbH"
      },
      "balanceSheet": {
        "assets": {
          "intangibleAssets": 12500,
          "propertyPlantEquipment": 450000,
          "financialAssets": 50000,
          "inventories": 120000,
          "receivables": 85000,
          "securities": null,
          "cashAndCashEquivalents": 95000,
          "prepaidExpenses": 2500,
          "totalAssets": 815000
        },
        "equityAndLiabilities": {
          "shareCapital": 35000,
          "capitalReserves": 100000,
          "retainedEarnings": 250000,
          "balanceSheetProfitOrLoss": 85000,
          "untaxedReserves": null,
          "provisions": 45000,
          "liabilities": 300000,
          "prepaidIncome": null,
          "totalEquityAndLiabilities": 815000
        }
      },
      "incomeStatement": {
        "revenues": 1250000,
        "changeInFinishedAndUnfinishedGoods": null,
        "otherOwnWorkCapitalized": null,
        "otherOperatingIncome": 15000,
        "costOfMaterials": -450000,
        "personnelExpenses": -420000,
        "depreciation": -85000,
        "otherOperatingExpenses": -190000,
        "financialResult": -12000,
        "ordinaryBusinessResult": 108000,
        "extraordinaryResult": null,
        "taxesOnIncome": -23000,
        "netIncome": 85000,
        "balanceSheetProfitOrLoss": 85000
      },
      "notes": {
        "hasNotes": true,
        "summary": "Der Jahresabschluss wurde nach den Vorschriften des UGB aufgestellt.",
        "attachments": []
      },
      "kpis": {
        "equityRatio": 0.5767,
        "leverage": 0.6383,
        "ebitMargin": 0.096
      }
    }
  }
}
GET/api/sanctions/filtersNew
Get Sanctions Metadata & Filters
Retrieves overview metadata for the EU Consolidated Financial Sanctions database, including all active sanction programmes, entity/person distribution, country counts, and cache updates.

Example Code

curl -X GET "https://firmafind.at/api/sanctions/filters" \
  -H "x-api-key: YOUR_API_KEY"

JSON Response

{
  "programmes": [
    { "code": "UKR", "count": 2150 },
    { "code": "BLR", "count": 310 },
    { "code": "IRN", "count": 480 }
  ],
  "countries": [
    { "code": "RU", "name": "Russian Federation", "count": 1890 },
    { "code": "BY", "name": "Belarus", "count": 280 }
  ],
  "totalEntities": 1420,
  "totalPersons": 4850,
  "lastUpdated": "2026-07-29T12:00:00.000Z"
}
GET/api/vat/validate
Validate VAT (VIES)
Check a European VAT number through the EU VIES system. For Austrian companies, the response includes matching Firmenbuch data.

Query Parameters

ParameterTypeRequiredDescription
country_codestringYesTwo-letter EU country code (e.g. AT, DE, CZ)
vat_numberstringYesVAT number without country prefix (e.g. U70497456)

Example Request

curl -X GET "https://firmafind.at/api/vat/validate?country_code=AT&vat_number=U70497456" \
  -H "x-api-key: YOUR_API_KEY"

Response (AT company with Firmenbuch match)

{
  "success": true,
  "data": {
    "valid": true,
    "countryCode": "AT",
    "vatNumber": "U70497456",
    "companyName": "Beispiel GmbH",
    "address": "Am Belvedere 1",
    "postalCode": "1100",
    "city": "Wien",
    "firmenbuchMatch": {
      "firmenbuchNumber": "FN 123456 a",
      "legalForm": "GmbH",
      "status": "aktiv"
    }
  }
}

Response (Non-AT / invalid VAT)

{
  "success": true,
  "data": {
    "valid": false,
    "countryCode": "DE",
    "vatNumber": "123456789",
    "companyName": "",
    "address": ""
  }
}

For non-Austrian VAT numbers, the response includes basic validation data from VIES without Firmenbuch enrichment. The firmenbuchMatch field is omitted when not applicable.

GET/api/edikteBeta
Search Edikte
Searches for publications (Edikte) in the Austrian Justizonline register. Returns a list of all matching publications.

Beta Feature

This endpoint is currently in active development. The response schema and parameters are subject to change without prior notice.

Query Parameters

ParameterTypeRequiredDescription
typestringJaEdikt type (e.g. ST, MV, EE, GB, PF)
pagenumberNeinPage number (default: 1)
pageSizenumberNeinResults per page (default: 10, max: 10000)

Example Request

curl -X GET "https://firmafind.at/api/edikte?type=ST&page=1" \
  -H "x-api-key: YOUR_API_KEY"
GET/api/edikte/:type/:idBeta
Get Edikt Details
Fetches full details of a specific Edikt using its type and ID.

Beta Feature

This endpoint is currently in active development. The response schema and parameters are subject to change without prior notice.

Example Request

curl -X GET "https://firmafind.at/api/edikte/ST/123456" \
  -H "x-api-key: YOUR_API_KEY"