Table of Contents
API Documentation
A REST API for modern developers. Complete reference for the firmafind API endpoints. Integrate Austrian company data seamlessly into your application.
Base URL
https://firmafind.atAuthentication
All API requests require an API key in the x-api-key Header:
x-api-key: YOUR_API_KEYExample Request
curl -X GET "https://firmafind.at/api/search?name=example" \
-H "x-api-key: YOUR_API_KEY"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.yamlQuick 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-clientBrowse live in swagger.io / Redoc
Paste the spec URL at editor.swagger.io for instant interactive docs.
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 Status | Daily Quota | Burst Limit | Authentication |
|---|---|---|---|
| Anonymous | 30 requests / day | 5 requests / min | No Key (IP-based) |
| Free User | 50 requests / day | 120 requests / min | API Key Required |
| Trial User | 500 requests / day | 30 requests / min | API Key Required |
| Subscriber | Unlimited | 120 requests / min | API 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:
| Header | Type | Description |
|---|---|---|
| X-RateLimit-Limit | integer | Your tier's maximum daily request allowance |
| X-RateLimit-Remaining | integer | Remaining requests available within the current daily window |
| X-RateLimit-Reset | timestamp | Unix epoch timestamp (seconds) when the daily quota resets |
| Retry-After | integer | Returned only on 429 responses. The number of seconds you must wait before retrying. |
| X-Usage-Policy | url | Link to the Acceptable Use Policy |
Best Practices & Tips
- Check headers to monitor usage and proactively pace requests.
- Handle
429status 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.
/api/search/publicNo API KeyPublic Company Search/api/sandbox/searchSandboxDeveloper Sandbox (Fictional Data)/api/searchSearch Companies/api/company/:fnrGet Company Details/api/company/changesGet Company Changes (Beta)/api/documentsList Documents/api/documents/:keyDownload Document/api/sanctions/searchSearch EU SanctionsNew/api/sanctions/filtersSanctions Metadata & FiltersNew/api/edikteSearch EdikteBeta/api/edikte/:type/:idGet Edikt DetailsBetaEndpoints in Detail
/api/search/publicNo API Key requiredTry for free
This endpoint requires no authentication. Perfect for a quick API test or integration into small projects. For full access and all fields, use the authenticated endpoint.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | Ja | Search term (min. 2 characters, e.g. company) |
| country | AT | CZ | Nein | Country (default: AT) |
Example Request
curl -X GET "https://firmafind.at/api/search/public?q=my%20company"Response Fields (reduced)
The public endpoint returns only basic information. Get the full dataset with the authenticated /api/search Endpoint.
| Field | Type | Description |
|---|---|---|
| name | string | Official company name |
| fnr | string | Company Register Number |
| city | string | Company seat (city) |
| rechtsform | string | Legal Form (z.B. GmbH, AG) |
| country | string | Country code (AT/CZ) |
JSON Example
{
"data": [
{
"name": "My Company GmbH",
"fnr": "123456a",
"city": "Wien",
"rechtsform": "Limited Liability Company (GmbH)",
"country": "AT"
}
],
"meta": {
"count": 1,
"rateLimit": {
"limit": 30,
"remaining": 29,
"resetAt": 1713571200
}
}
}Rate Limiting
IP-based Limit
Per IP address, reset daily. No API key required.
/api/sandbox/searchSandbox / API Key Required (0 Credits)Perfect for AI Agent Prototyping
Testing JSON schemas with LLMs often wastes trial API credits. Use this endpoint to receive the exact schema output of our production API without consuming any credits. An API key is required (sign up is free). Slowed by design (2500ms response time) to avoid production abuse.
Authentication
Requires your API key in the x-api-key header. Sandbox requests do not consume your account credits (0 credit cost).
x-api-key: YOUR_API_KEYQuery Parameters
All query parameters are accepted but do not affect the returned result. The API always returns the same three mock companies.
| Parameter | Type | Required | Description |
|---|---|---|---|
| q / query | string | Nein | Search term (e.g. My Company) |
| zip | string | Nein | Postal Code |
| uid | string | Nein | UID number |
Example Request
curl -X GET "https://firmafind.at/api/sandbox/search?q=test"
-H "x-api-key: YOUR_API_KEY"Response Fields
The response structure matches the main company search schema:
| Field | Type | Description |
|---|---|---|
| fnr | string | Firmenbuchnummer (Company Register Number) |
| name | string | Official company name |
| sitz | string | Company seat (city) |
| rechtsform | string | Legal Form (e.g. Gesellschaft mit beschränkter Haftung) |
| status | string | Status (e.g. aktiv) |
| gericht | string | Responsible local court |
| country | string | Country code (AT/CZ) |
| _meta | object | Sandbox notice metadata for testing integrations |
JSON Response
{
"data": [
{
"fnr": "123456a",
"name": "AlpenQuelle Getränke GmbH",
"sitz": "Salzburg",
"rechtsform": "Gesellschaft mit beschränkter Haftung (GmbH)",
"status": "aktiv",
"gericht": "Landesgericht Salzburg",
"country": "AT",
"_meta": {
"message": "This is a static sandbox response. Upgrade to production for live data.",
"hint": "Real API endpoints provide live queries across registered Austrian companies."
}
},
{
"fnr": "789012b",
"name": "GipfelMarkt Supermärkte AG",
"sitz": "Innsbruck",
"rechtsform": "Aktiengesellschaft (AG)",
"status": "aktiv",
"gericht": "Landesgericht Innsbruck",
"country": "AT",
"_meta": {
"message": "This is a static sandbox response. Upgrade to production for live data.",
"hint": "Production API returns historical balance sheets, managers, shareholder details, and official annual reports."
}
},
{
"fnr": "345678c",
"name": "NovaTech Software Entwicklung GmbH",
"sitz": "Wien",
"rechtsform": "Gesellschaft mit beschränkter Haftung (GmbH)",
"status": "aktiv",
"gericht": "Handelsgericht Wien",
"country": "AT",
"_meta": {
"message": "This is a static sandbox response. Upgrade to production for live data.",
"hint": "Test integrations easily; the schema structure is identical to our live production JSON payload."
}
}
],
"meta": {
"count": 3,
"is_sandbox": true,
"simulated_latency_ms": 2500
}
}Rate Limiting
User-based Sandbox Limit
Per user account, reset sliding window. Exceeding this limit returns HTTP Status 429 Too Many Requests with standard rate-limit headers.
/api/searchQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Ja | Search term for company name (e.g. sons) |
Example Code
curl -X GET "https://firmafind.at/api/search?name=my%20company" \
-H "x-api-key: YOUR_API_KEY"Response Schema
| Field | Type | Description |
|---|---|---|
| fnr | string | Company Register Number (eindeutige Kennung) |
| name | string | Official company name |
| sitz | string | Company seat (city) |
| rechtsform | string | Legal form of the company (e.g. GmbH, e.U.) |
| status | string | Company status (active or deleted) |
| gericht | string | Responsible commercial court |
JSON Example
{
"success": true,
"data": [
{
"fnr": "579180k",
"name": "Chladek & Sons GmbH",
"sitz": "Wien",
"rechtsform": "Limited Liability Company (GmbH)",
"status": "aktiv",
"gericht": "Handelsgericht Wien"
},
{
"fnr": "502231a",
"name": "LOS & Sons GmbH",
"sitz": "Innsbruck",
"rechtsform": "Limited Liability Company (GmbH)",
"status": "aktiv",
"gericht": "Landesgericht Innsbruck"
}
],
"meta": {
"count": 8
}
}/api/company/:fnrURL Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| fnr | string | Ja | Company 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
| Field | Type | Description |
|---|---|---|
| fnr | string | Company Register Number |
| euid | string | European Business Identifier |
| companyName | string | Official company name |
| isActive | boolean | Status ob Firma aktiv ist |
| legalForm | string | Full legal form description |
| address | object | Address data (street, postal code, city, seat) |
| management | array | List of managing directors with roles |
| transactions | array | Firmenbuch transaction history |
| foundationDate | string | Foundation 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
}
}/api/company/changesBetaQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| from | string | Ja | Start date in YYYY-MM-DD format (falls back to von). The date range between from and to cannot exceed 7 days. |
| to | string | Ja | End date in YYYY-MM-DD format (falls back to bis). The date range between from and to cannot exceed 7 days. |
| changeType | string | Nein | Filter by the type of change. Supported values:
|
| court | string | Nein | Court code filter (e.g. 007 for Landesgericht Linz). Falls back to gericht. |
| legalForm | string | Nein | Legal form code filter (e.g. AG, GMBH). Falls back to rechtsform. |
| industry | string | Nein | Filter by industry using rule-based classification of company names. Supported values:
|
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
| Field | Type | Description |
|---|---|---|
| fnr | string | Company Register Number (Firmenbuchnummer, z.B. 875 m) |
| vnr | number | Execution Number (Vollzugsnummer, z.B. 7). Indicates the version sequence of changes. |
| date | string | Execution Date (Vollzugsdatum, YYYY-MM-DD) |
| changeType | string | Type 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
}
}/api/documentsQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| fnr | string | Ja | Company 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
| Field | Type | Description |
|---|---|---|
| key | string | Unique document key for download |
| fnr | string | Company Register Number |
| dokumentart | object | Document type with code and description |
| contentTypee | string | MIME type (application/pdf or application/xml) |
| stichtag | string | Balance 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"
}
}
}/api/documents/:keyannualReport with Balance Sheet, Income Statement, Notes, and KPIs). PDFs and other documents return standardized metadata along with the Base64 file payload.URL Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | Unique 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
| Field | Type | Description |
|---|---|---|
| type | string | Document classification (annual_report, pdf_document, xml_document) |
| metadata | object | Standardized document metadata (FNR, Aktenzeichen, dates, court, size) |
| annualReport | object | null | Structured annual financial statement (JAb 3.32) with Balance Sheet, Income Statement, Notes, and KPIs |
| raw | object | File 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
}
}
}
}/api/sanctions/searchNew/api/sanctions/check)Compliance Notice & Disclaimer
Results returned by this screening endpoint represent potential matches based on official public sanctions records and require manual human review for formal KYC/AML clearance.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Ja | Name of company, legal entity, or person to screen (e.g. VTB Bank) |
| type | string | Nein | Subject type filter: entity or person (default: entity) |
| country | string | Nein | 2-letter ISO country code or country name filter (e.g. RU, BY) |
| programme | string | Nein | EU sanctions regime code (e.g. UKR, BLR) |
| minConfidence | number | Nein | Minimum fuzzy matching score (0-100, default: 50) |
Example Code
curl -X GET "https://firmafind.at/api/sanctions/search?name=VTB%20Bank&type=entity&minConfidence=60" \
-H "x-api-key: YOUR_API_KEY"Response Schema
| Field | Type | Description |
|---|---|---|
| overallStatus | string | potential_match_found or no_potential_match_found |
| disclaimer | string | Official legal disclaimer for KYC/AML review |
| source | object | Source publisher information, official dataset URL, and screening timestamp |
| total | number | Number of matching records found |
| results | array | List of matching entity/person records with confidence score, EU reference number, legal act, aliases, and birthdates |
JSON Example
{
"overallStatus": "potential_match_found",
"query": "VTB Bank",
"filters": {
"type": "entity",
"country": null,
"programme": null,
"minConfidence": 60
},
"total": 1,
"results": [
{
"status": "potential_match",
"matchedName": "VTB BANK PJSC",
"confidence": 92,
"matchReason": "Strong name match",
"euReferenceNumber": "EU.7483.92",
"logicalId": "13425",
"legalAct": "Council Regulation (EU) No 269/2014",
"sourceName": "EU Consolidated Financial Sanctions List",
"sourceUrl": "https://www.eeas.europa.eu/eeas/european-union-sanctions_en",
"sourceUpdatedAt": "2026-07-28T00:00:00.000Z",
"aliases": [
"VTB BANK (PUBLIC JOINT STOCK COMPANY)",
"VOSTOCHNY EXPRESS BANK"
],
"subjectType": "entity",
"programme": "UKR",
"regulationNumber": "EU 269/2014",
"citizenships": [],
"countries": ["RU"],
"birthdates": [],
"remark": "Major financial institution under EU sanctions regime."
}
]
}/api/sanctions/filtersNewExample 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"
}/api/vat/validateQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
country_code | string | Yes | Two-letter EU country code (e.g. AT, DE, CZ) |
vat_number | string | Yes | VAT 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.
/api/edikteBetaBeta Feature
This endpoint is currently in active development. The response schema and parameters are subject to change without prior notice.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Ja | Edikt type (e.g. ST, MV, EE, GB, PF) |
| page | number | Nein | Page number (default: 1) |
| pageSize | number | Nein | Results 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"/api/edikte/:type/:idBetaBeta 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"