API-Dokumentation

Getting Started

Search & Data

Financials

Monitoring & Webhooks

API Documentation

Unified API for Austrian companies. Search, verify and retrieve structured company data from Austrian register sources through one API. Company register data, available filings, VAT validation and email validation. One API key. One JSON format.

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"

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 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

Credit Economics

firmafind operates on transparent, usage-based credit pricing aligned directly with our core capabilities. Volume-friendly credits for search and onboarding, premium credits for normalized financials, and flat per-company retention pricing for monitoring — never charged for empty checks.

Capability	Cost	Job-to-be-Done (JTBD)	Endpoints
Search & Master Data	1 credit	Is the company real, active, who can sign?	/api/search, /api/company/:fnr
VAT Validation	1 credit	Is there a tax registration issue?	/api/vat/validate
Developer Sandbox	0 credits	Integration testing with mock Austrian entities	/api/sandbox/search
firmafind Financials	15 credits	Normalized multi-year balance sheets & P&L	/api/financials/:fnr
Raw Filing Documents	1–10 credits	List filings (1 credit) or download PDF/XML (10 credits)	/api/documents, /api/documents/:key
Watchlists & Webhooks	0 credits	Included in plan watchlist quota (0 credits / delivery)	/api/monitors/*
Company Changes Feed	0–1 credit	1 credit per page; 0 credits when no changes found	/api/company/changes

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 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.

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.

Download openapi.yaml View raw spec

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.

AI Agent Ready/api/mcp

SSE & HTTP Streamable

MCP Server

Connect AI assistants and coding agents (Claude Desktop, Cursor, OpenCode, Windsurf, LangChain, n8n) directly to Austrian company registers and filings. Requires a paid subscription (Starter, Pro or Business) or active trial.

Endpoint URL

https://firmafind.at/api/mcp

Available Agent Tools

Tool Name	Cost	Description
search_austrian_company	1 credit	Search Firmenbuch by name, court, or legal form.
get_company_details	1 credit	Complete Firmenbuch extract (address, capital, directors, shareholders).
get_company_changes	1 credit	Query historical changes, newly registered companies, or deletions.
list_company_documents	1 credit	List available balance sheets, agreements, and filed documents.
download_company_document	10 credits	Download document & structured annual financial statements XML as JSON.
list_edikte	1 credit	Search Austrian court edicts for insolvencies and announcements.
get_edict_details	1 credit	Get full publication details for an insolvency or court notice.
validate_email	1 credit	Validate email deliverability (syntax, MX, disposable, typo).

Client Setup Guides

In Cursor / Windsurf Settings → MCP Servers → Add New Remote Server:

{
 "name": "firmafind",
 "url": "https://firmafind.at/api/mcp",
 "headers": {
 "x-api-key": "YOUR_API_KEY"
 }
}

Agent Skill (SKILL.md) & GitHub Repository

GitHub Repository View raw SKILL.md

Equip autonomous AI coding assistants (Cursor, OpenCode, Claude, Windsurf, Antigravity) with structured domain knowledge for Austrian corporate research and balance sheet extraction. Explore the open-source integration examples on GitHub.

# Download work skill into your agent directory
curl -s "https://firmafind.at/skill.md" >.agents/skills/firmafind/SKILL.md

Endpoints in Detail

Search & Data

Unified Austrian company register search, normalized master data, authorized signatories (vertretungsberechtigte Personen), GISA trade license checks, and VIES VAT validation.

GET/api/search

Search Companies

Fuzzy search across Austrian registered commercial entities (Firmenbuch) by company name or search phrase. Returns normalized identity, legal form, Firmenbuchnummer (FNr), registered seat, and active court jurisdiction. Ideal for onboarding autofill and customer search.

Query 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	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
 }
}

GET/api/company/:fnr

Get Company Details & Signatories

Retrieves complete, normalized company master data from the Austrian Firmenbuch. Includes legal structure, active status, authorized managing directors and signatories (vertretungsberechtigte Personen), registered business address, and GISA trade license references. The primary lookup endpoint for verifying company identity, representation powers, and hard stops.

URL 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	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)
gisa	object	GISA trade register data (isRegistered, count, trades)

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"
      }
    ],
    "gisa": {
      "isRegistered": true,
      "count": 1,
      "trades": [
        {
          "gisaNumber": "31365864",
          "tradeCode": "500314",
          "description": "Dienstleistungen in der automatischen Datenverarbeitung",
          "industry": "it",
          "isDormant": false
        }
      ]
    },
  },
  "meta": {
    "cost": 0
  }
}

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

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.

GET / POST/api/email/validate

Validate email

Verify email deliverability with syntax, MX/DNS, disposable and typo checks. Includes deliverability score (0 to 100) and risk level. Free checker at /tools/email-validation.

Authentication

Requires x-api-key header. Cost: 1 credit. Free tool requires no key.

x-api-key: YOUR_API_KEY

Request

curl -X GET "https://firmafind.at/api/email/[email protected]" \
 -H "x-api-key: YOUR_API_KEY"

Parameters

Parameter	Type	Required	Description
email (query) / email (body)	string (email)	Yes	Email to validate (max 254 chars). Use query `?email=` for GET or JSON `{"email": "..."}` for POST.

Response

{
 "data": {
  "email": "[email protected]",
  "valid_syntax": true,
  "domain": "firmafind.at",
  "local_part": "office",
  "is_disposable": false,
  "is_role": false,
  "is_free": false,
  "mx_valid": true,
  "mx_records": ["mail.firmafind.at"],
  "typo_suggestion": null,
  "did_you_mean": null,
  "result": "valid",
  "subresult": "deliverable",
  "reason": "accepted_email",
  "deliverability_score": 95,
  "risk_level": "low",
  "catch_all": null
 },
 "meta": { "credits_used": 1 }
}

GET/api/sandbox/search

Developer Sandbox Search

Fictional company search endpoint designed for testing structures and prototyping without wasting API credits or LLM tokens. Requires authentication (free sign-up), but is completely free to call. Returns a static array of exactly three fictional companies with an artificial 2.5s latency simulation.

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_KEY

Query 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	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
_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",
 "_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",
 "_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 annual reports."
 }
 },
 {
 "fnr": "345678c",
 "name": "NovaTech Software Entwicklung GmbH",
 "sitz": "Wien",
 "rechtsform": "Gesellschaft mit beschränkter Haftung (GmbH)",
 "status": "aktiv",
 "gericht": "Handelsgericht Wien",
 "_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

5 Requests/Minute

Per user account, reset sliding window. Exceeding this limit returns HTTP Status 429 Too Many Requests with standard rate-limit headers.

GET/api/search/public

Public Company Search

Free access to company data without an API key. Ideal for testing and simple lookups. Reduced data scope, IP-based rate limiting (30 requests/day).

Try 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)

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	company name
fnr	string	Company Register Number
city	string	Company seat (city)
rechtsform	string	Legal Form (z.B. GmbH, AG)

JSON Example

{
 "data": [
 {
 "name": "My Company GmbH",
 "fnr": "123456a",
 "city": "Wien",
 "rechtsform": "Limited Liability Company (GmbH)"
 }
 ],
 "meta": {
 "count": 1,
 "rateLimit": {
 "limit": 30,
 "remaining": 29,
 "resetAt": 1713571200
 }
 }
}

Rate Limiting

IP-based Limit

30 Requests/Tag

Per IP address, reset daily. No API key required.

Financials

Multi-year balance sheets and income statements (GuV) normalized across Austrian JAb filing schemas alongside company register filings. Pure reported figures and financial ratios without legacy credit bureau jargon.

GET/api/financials/:fnr

Get Company Financials

Returns normalized balance sheet and income statement data from filed annual financial statements for an Austrian company. Supports up to 5 reporting periods with financial ratios and year-over-year changes.

URL Parameters

Parameter	Type	Required	Description
fnr	string	Ja	Company register number (e.g. `344483v`)

Query Parameters

Parameter	Type	Required	Description
years	number	Nein	Number of reporting periods to return, between 1 and 5 (default: 5)
include	string	Nein	Comma-separated sections to include: `summary`, `periods`, `changes`, `evidence`, `documents`
refresh	boolean	Nein	Bypass cache to fetch live data from the register (paid plans only, max 5/hour)

Example Code

curl -X GET "https://firmafind.at/api/financials/344483v?years=2" \
  -H "x-api-key: YOUR_API_KEY"

Response Schema

Field	Type	Description
company	object	Company details (registration number, name, legal form, active status)
summary	object	Overview of filing dates and total period counts
periods	array	Annual statements with balance sheet metrics, income statement, and ratios
changes	object	Year-over-year absolute and percentage changes between the latest two periods
quality	object	Filing quality status and notices (such as missing fields or PDF-only filings)
meta	object	API cost, remaining balance, and schema version

JSON Example

{
  "data": {
    "company": {
      "fnr": "344483v",
      "name": "Example GmbH",
      "legalForm": "Gesellschaft mit beschränkter Haftung",
      "isActive": true
    },
    "summary": {
      "latestPeriodEnd": "2024-12-31",
      "latestFiledAt": "2025-09-01",
      "availablePeriodCount": 2,
      "structuredPeriodCount": 2
    },
    "periods": [
      {
        "periodEnd": "2024-12-31",
        "periodStart": "2024-01-01",
        "filedAt": "2025-09-01",
        "currency": "EUR",
        "source": {
          "documentKey": "344483_2024_XML",
          "format": "xml",
          "filingScope": "full_annual_statement"
        },
        "metrics": {
          "totalAssets": 1250000,
          "equity": 390000,
          "liabilities": 720000,
          "provisions": 140000,
          "cashAndCashEquivalents": 80000,
          "revenue": 2100000,
          "operatingResult": 95000,
          "netIncome": 46000,
          "employees": null
        },
        "ratios": {
          "equityRatio": 0.312,
          "debtRatio": 0.576,
          "debtToEquity": 1.8462
        },
        "availability": {
          "totalAssets": "reported",
          "equity": "reported",
          "liabilities": "reported",
          "provisions": "reported",
          "cashAndCashEquivalents": "reported",
          "revenue": "reported",
          "operatingResult": "reported",
          "netIncome": "reported",
          "employees": "not_mapped"
        }
      }
    ],
    "changes": {
      "status": "available",
      "comparedPeriodEnd": "2023-12-31",
      "currentPeriodEnd": "2024-12-31",
      "absolute": {
        "totalAssets": 95000,
        "equity": 30000,
        "liabilities": 65000,
        "netIncome": 8000
      },
      "relative": {
        "totalAssets": 0.0823,
        "equity": 0.0833,
        "liabilities": 0.0992,
        "netIncome": 0.2105
      }
    },
    "quality": {
      "status": "complete",
      "returnedPeriods": 2,
      "structuredYears": 2,
      "warnings": []
    }
  },
  "meta": {
    "cost": 25,
    "remainingBalance": 9975,
    "schemaVersion": "2026-09-01"
  }
}

Extracted Financial Metrics

Field	Type	Description
totalAssets	number \| null	Total assets (Bilanzsumme)
equity	number \| null	Equity (Eigenkapital)
liabilities	number \| null	Liabilities (Verbindlichkeiten)
provisions	number \| null	Provisions (Rückstellungen)
cashAndCashEquivalents	number \| null	Cash and bank balances
revenue	number \| null	Revenue (Umsatzerlöse, null if not disclosed)
operatingResult	number \| null	Operating result (EBIT)
netIncome	number \| null	Net income or loss (Jahresüberschuss / -fehlbetrag)
employees	number \| null	Average headcount (null if not reported)

Calculated ratios include equityRatio (equity / totalAssets), debtRatio (liabilities / totalAssets), and debtToEquity (liabilities / equity). Each metric carries an availability status (reported, not_disclosed, not_mapped, or not_available_in_source_format). If a company only filed a PDF for a period, metrics return null.

Credits & Pricing

Single Period

15 Credits

Query with years=1.

Multi-Period History

25 Credits

Query with years=2..5. Includes year-over-year changes.

Failed requests (4xx or 5xx errors) cost 0 credits. Test free in the sandbox at /api/sandbox/financials/:fnr. Original filings can be downloaded via /api/documents/:key (10 credits).

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

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"
 }
 }
}

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

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
      }
    }
  }
}

Monitoring & Webhooks

Automated change detection for monitored companies. Track management updates, insolvency notices (Edikte), and new annual filings via cursor-based events or HMAC-signed webhooks.

REST + Webhooks/api/monitorsPrivate Preview

Watchlists, Events & Webhooks

Put companies on a watchlist and get notified about new filings, insolvency notices, and register changes — via pull (events API) or push (signed webhooks). Monitoring calls cost 0 credits; usage counts against your watchlist quota instead. Currently in private preview — contact support to enable it for your account.

Watchlist quota by plan

Plan	Watched companies
Free / Trial	2
Starter	25
Pro	100
Business	500

Watchlists

GET / POST /api/monitors list and create watchlists, GET / DELETE /api/monitors/:id inspect and delete them.

curl -X POST "https://firmafind.at/api/monitors" \
 -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
 -d '{"name": "Key suppliers"}'

Watched companies

POST /api/monitors/:id/companies accepts a single fnr, an fnrs array, or a companies array. DELETE /api/monitors/:id/companies/:fnr removes one.

curl -X POST "https://firmafind.at/api/monitors/MONITOR_ID/companies" \
 -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
 -d '{"fnrs": ["66209t", "50935w"]}'

Pull: change events

GET /api/monitors/:id/events returns filings, insolvency notices, and register changes for the watchlist. Paginate with sinceCursor (from the previous nextCursor), filter with types, fnr, from / to. Empty result sets return HTTP 200 with {"data": [], "meta": {"count": 0}} — never poll on a timer without a cursor.

curl "https://firmafind.at/api/monitors/MONITOR_ID/events?limit=20" \
 -H "x-api-key: YOUR_API_KEY"

Push: signed webhooks

GET / POST /api/monitors/:id/subscriptions manages target URLs, POST /api/monitors/:id/subscriptions/:subId/test sends a test ping. Every delivery carries an X-Firmafind-Signature header with the HMAC-SHA256 of the raw JSON body — always verify it before trusting a payload.

curl -X POST "https://firmafind.at/api/monitors/MONITOR_ID/subscriptions" \
 -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
 -d '{"url": "https://example.com/hooks/firmafind"}'

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

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: `new`: Maps to Neueintragung (company creation/registration) `change`: Maps to Änderung (company detail updates) `delete`: Maps to Löschung (company deletion/removal)
court	string	Nein	Court code filter (e.g. `007` for Landesgericht Linz). Falls back to `gericht`.
legalForm	string	Nein	Legal form code filter (max. 3 characters, e.g. `GES` for GmbH, `AG`). Friendly names like `GmbH` are accepted and mapped automatically. Falls back to `rechtsform`.
industry	string	Nein	Filter 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

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
 }
}

GET/api/edikte

Search Edikte

Searches for court notices and insolvency filings (Edikte) in the Austrian register. Filter by edict type, publication dates, or modification timestamps.

Query Parameters

Parameter	Type	Required	Description
type	string	Yes	Edikt type code: `MV` (Insolvencies & Restructuring), `FB` (Firmenbuch announcements), `ST` (Auctions), `EE` (Edicts), `GB` (Land register), `PF` (Distraints)
page	number	No	Page number (default: 1)
pageSize	number	No	Results per page (default: 10, max: 100)
publishedFrom	string	No	Filter publications starting from date (`YYYY-MM-DD`)
publishedUntil	string	No	Filter publications up to date (`YYYY-MM-DD`)
modifiedFrom	string	No	Filter by modification timestamp from (ISO-8601 format)
modifiedUntil	string	No	Filter by modification timestamp until (ISO-8601 format)

Example Request

curl -X GET "https://firmafind.at/api/edikte?type=MV&page=1&pageSize=10" \
 -H "x-api-key: YOUR_API_KEY"

Example Response

{
 "data": {
 "edikte": [
 {
 "id": 123456,
 "aktenzeichen": "24 S 12/25a",
 "gericht": "Handelsgericht Wien",
 "bekanntmachungsDatum": "2026-08-20",
 "schuldner": {
 "name": "Musterbau GmbH",
 "anschrift": "Musterstraße 1, 1010 Wien",
 "art": "JURISTISCH"
 },
 "verwalter": {
 "name": "Dr. Max Mustermann (Masseverwalter)"
 }
 }
 ],
 "total": 1,
 "page": 1,
 "pageSize": 10
 }
}

GET/api/edikte/:type/:id

Get Edikt Details

Fetches full details and public court publication text of a specific Edikt by its type and unique ID.

Path Parameters

Parameter	Type	Required	Description
type	string	Yes	Edikt type code (e.g. `MV`, `FB`, `ST`)
id	number	Yes	Unique numeric ID of the edict publication

Example Request

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

Example Response

{
 "data": {
 "id": 123456,
 "aktenzeichen": "24 S 12/25a",
 "gericht": "Handelsgericht Wien",
 "bekanntmachungsDatum": "2026-08-20",
 "kurzbeschreibung": "Eröffnung des Konkursverfahrens",
 "beschreibung": "Mit Beschluss vom 20.08.2026 wurde das Konkursverfahren über das Vermögen eröffnet...",
 "schuldner": {
 "name": "Musterbau GmbH",
 "anschrift": "Musterstraße 1, 1010 Wien"
 },
 "verwalter": {
 "name": "Dr. Max Mustermann"
 }
 }
}

Table of Contents

API Documentation

Base URL

Authentication

Example Request

Rate Limit Tiers

Credit Economics

When Exceeded

Best Practices & Tips

Spec URL

Quick start

Endpoint URL

Available Agent Tools

Client Setup Guides

Agent Skill (SKILL.md) & GitHub Repository

Endpoints in Detail

Search & Data

Query Parameters

Example Code

Response Schema

JSON Example

URL Parameters

Example Code

Response Schema

JSON Example

Query Parameters

Example Request

Response (AT company with Firmenbuch match)

Response (Non-AT / invalid VAT)

Authentication

Request

Parameters

Response

Perfect for AI Agent Prototyping

Authentication

Query Parameters

Example Request

Response Fields

JSON Response

Rate Limiting

User-based Sandbox Limit

Try for free

Query Parameters

Example Request

Response Fields (reduced)

JSON Example

Rate Limiting

IP-based Limit

Financials

URL Parameters

Query Parameters

Example Code

Response Schema

JSON Example

Extracted Financial Metrics

Credits & Pricing

Single Period

Multi-Period History

Query Parameters

Example Code

Response Schema

JSON Example

URL Parameters

Example Code

Response Schema

JSON Example (Jahresabschluss)

Monitoring & Webhooks

Watchlist quota by plan

Watchlists

Watched companies

Pull: change events

Push: signed webhooks

Query Parameters

Example Code

Response Schema

Example Response

Query Parameters

Example Request

Example Response

Path Parameters