---
name: firmafind
description: |
 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 insolvency notices. One API key. One JSON format. Built for product workflows, internal tools and AI agents.
license: MIT
version: "2.0.0"
---

# firmafind Agent Skill

This skill guides AI agents in querying Austrian business register data, retrieving corporate records, financial statements, and connecting to the firmafind Hosted MCP Server or REST API.

## Overview

firmafind converts Austrian Firmenbuch and Edikte data into structured JSON APIs and an agent-ready Hosted Model Context Protocol (MCP) server.

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 insolvency notices. One API key. One JSON format.

Target domain:
- **Company Registration Numbers (Firmenbuchnummer / `fnr`)**: Numbers followed by a single lowercase letter, e.g. `123456x` or `fn123456x`.
- **Legal Forms**: `GmbH` (Gesellschaft mit beschränkter Haftung), `AG` (Aktiengesellschaft), `KG`, `OG`, `e.U.` (eingetragenes Einzelunternehmen).
- **Data Points**: Management structure (Geschäftsführer, Prokuristen), share capital, registered seat, annual financial reports (Jahresabschlüsse) and insolvency notices (Edikte).

## Authentication

All API and MCP requests require an API key in the `x-api-key` HTTP header, `Authorization: Bearer` header, or `?apiKey=` query parameter.

```http
GET /api/companies?name=Example HTTP/1.1
Host: firmafind.at
x-api-key: ff_live_your_key_here
```

API keys can be managed in the dashboard at https://firmafind.at/dashboard/keys.

## Hosted MCP server integration (`/api/mcp`)

Connect Claude Desktop, Cursor, OpenCode, or Windsurf directly to the hosted server. Requires a paid subscription (Starter, Pro or Business) or active trial (free plan is REST only):

- **Server URL**: `https://firmafind.at/api/mcp`
- **Transport**: Web Standards Streamable HTTP / Server-Sent Events (SSE)
- **Header**: `x-api-key: YOUR_API_KEY`

### Available MCP tools

1. `search_austrian_company`: Search Firmenbuch by name, court, or legal form.
2. `get_company_details`: Complete registration extract (address, capital, directors, shareholders).
3. `get_company_changes`: Historical register changes and new formations across a date range.
4. `list_company_documents`: List available annual reports, balance sheets, and filed documents.
5. `download_company_document`: Download document contents & structured annual financial report XML parsed as JSON (costs 10 credits).
6. `list_edikte`: Search Austrian court edicts for corporate insolvencies.
7. `get_edict_details`: Publication details for an insolvency or court notice.

## REST API quick reference

- **Base URL**: `https://firmafind.at`
- **Auth Header**: `x-api-key: YOUR_API_KEY`
- **MCP URL**: `https://firmafind.at/api/mcp`

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/companies/search` | GET | Search companies by name, legal form, court |
| `/api/companies/{fnr}` | GET | Full company details by Firmenbuchnummer |
| `/api/documents` | GET | List available filings for a company |
| `/api/documents/{key}` | GET | Download document (PDF/XML + parsed JSON) |
| `/api/edikte` | GET | Search insolvency edicts |
| `/api/edikte/{type}/{id}` | GET | Edikt details |
| `/api/vat/validate` | GET | VAT validation via VIES |

## Error handling and credits

- Standard lookups cost **1 credit**.
- Annual financial report / document downloads cost **10 credits**.
- HTTP 401: Invalid or missing API key.
- HTTP 402 / 429: Credit balance exhausted or quota reached.