# handelsregister.ai > REST API for official German company data (Handelsregister): company master data, Signals (normalized commercial-register changes searchable across companies), financials, management, shareholders, UBOs, shareholdings, M&A transactions, insolvencies, news, and register documents. Credit-based billing (1 credit = EUR 0.01 base price); features are only charged when they return data. There is no official API for the German commercial register (Handelsregister). handelsregister.ai is an independent API by Fusionbase GmbH that delivers official company data from the Handelsregister, Bundesanzeiger and insolvency notices as structured JSON, in real time on request, for software and AI agents. Base URL: `https://handelsregister.ai/api` Machine-readable spec: https://handelsregister.ai/openapi.json (every parameter, field and error in detail; this file is generated from it) Human documentation: https://handelsregister.ai/en/documentation (German: https://handelsregister.ai/de/documentation) ## Authentication - API key header (recommended): `x-api-key: YOUR_API_KEY` - API key query parameter (legacy): `?api_key=YOUR_API_KEY` (rejected with 400 on `/api/v1/account/*`) - Bearer token: `Authorization: Bearer `. Create one with your API key via `POST /api/v1/auth/tokens/create` (abilities default to `api:data` + `account:read`; data endpoints accept any valid token, account reads need `account:read`). Managing API keys needs the admin token, created on the account's API-keys page (valid one year; a new one replaces the old). - Token create body: `token_name` (required), optional `abilities` (default `api:data` and `account:read`; `*` maps to those two; `monitoring:manage` is allowed; `account:keys` is always removed) and `expires_at` (a future date). Answers 201 with the `token`, shown only once. OAuth access tokens (see "AI agents & MCP") are Bearer tokens too. - Get an API key: sign up at https://handelsregister.ai; registration creates your first API key, which you find in the dashboard. Until the account's e-mail address is verified, the API answers 403 with `verification_required: true`. - Under each endpoint below, "Auth" names the accepted credentials where they differ from these three; "Parameters" lists every parameter with its type and limits, "Responses" every documented status code. ## Endpoints - `GET /api/v1/search-organizations` - find companies by name (`q`, 2-500 chars, names only; omit it rather than sending it empty) and/or a JSON-encoded `filters` object; at least one is required (else 400). 1 credit per page, an empty page included; refusals and errors cost 0. Paging: `limit` 1-30 (default 10) and `skip`; a search reaches at most the first 10,000 hits (`skip` >= 10000 fails), there is no cursor, so split large queries by state, postal code or date. `total` is an estimate, read it with `total_relation` (`exact`, `upper_bound`, `lower_bound`, `unknown`). `sort` = relevance, distance (needs the geo filters), registration_date, revenue, profit, employees, total_assets, equity, liabilities, cash, equity_ratio, financial_year, share_capital, last_activity, largest_share_ratio, management_size, md_oldest_birth_date or md_youngest_birth_date, with `order=asc|desc`; `match_context=1` fills `_match_context` per hit. Base filters (any plan): `registration_date_from`/`registration_date_to` (YYYY-MM-DD), `legal_form_code` (one exact string, e.g. `GmbH`), `legal_form_category`, `legal_form_liability_type`, `industry_code` (5-digit WZ2025 leaf code like `62.10.1`, or a list), `active`, `status` (ACTIVE, INACTIVE, TERMINATED, DISSOLVED, INSOLVENT), `country` (`DEU`), `state` (German name, e.g. `Bayern`), `county`, `city`, `postal_code`, `street`, `house_number`, `location_coordinates` (`{"lat":..,"lon":..}`) together with `location_max_distance_km`, `registration_type` (HRA, HRB, GnR, PR, VR, GsR), `registration_authority_name` (court), `registration_number` (number only), `company_size_category`, `emp_size_category`, `pl_company_size_category` (micro|small|medium|large) and `financial_filters` (`{"gte":..,"lte":..}` ranges on emp_count, pl_revenue, pl_net_income, pl_ebit, bs_assets_total, bs_equity_total, bs_liabilities_total, bs_cash_and_equivalents, bs_cash_to_liabilities, bs_equity_ratio, bs_debt_to_assets; e.g. `{"pl_revenue": {"gte": 1000000, "lte": 5000000}}`). Register groups: `owner_filters`, `ownership_filters`, `executive_filters`, `lifecycle_filters` (Pro or Max; other plans get 403 `subscription_required` with `meta.blocked_filters`, 0 credits) and `related_person_filters`, `related_organization_filters`, `activity_filters`, `capital_filters`, `group_signal_filters` (any plan); field values are a scalar, a list (any of), a range `{gte,lte,gt,lt}` or `{exists: bool}`, dates YYYY[-MM[-DD]], ratios 0-1; full field list in the OpenAPI schema `OrganizationSearchFilters`. Values are case-sensitive: an unknown key or field is a 422 (0 credits), an unknown value returns no hits and is charged. Response: `results[]` with `entity_id` (use it as `q` in fetch-organization), `name`, `registration`, `address`, `registration_date`, `purpose`, `status_normalized`, `_match_context`; `total` with `total_relation` and `total_exact`; `meta`. - Parameters: `q` (query, string, 2-500 chars), `skip` (query, integer, 0-9999, default 0), `limit` (query, integer, 1-30, default 10), `filters` (query, JSON, schema `OrganizationSearchFilters`), `sort` (query, one of relevance, distance, registration_date, revenue, profit, employees, total_assets, equity, liabilities, cash, equity_ratio, financial_year, share_capital, last_activity, largest_share_ratio, management_size, md_oldest_birth_date, md_youngest_birth_date (open list)), `order` (query, asc|desc), `match_context` (query, 0|1, default 0), `Idempotency-Key` (header, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Responses: 200, 400, 401, 402, 403, 408, 422, 429, 500, 502. - `GET /api/v1/fetch-organization` - full company profile. `q` accepts the `entity_id` from search (most reliable), the register court with register type and number (e.g. `Ansbach HRB 6089`; a number without court and type is ambiguous), or a company name (best with legal form and city; an ambiguous name may return any one of the matching companies or 404). Paid data features (see below): repeat `feature=` or send `features=a,b`; unknown names are ignored. `ai_search=on-default` (+20 credits) enables AI enrichment/fuzzy resolution; in AI mode `purpose` is a short AI summary instead of the registered business object, web data fills contact data and keywords, and a company not in the register can come back as a web-only profile (`registration: null`, `entity_id` starting with `AI_TMP_`). `realtime_mode=handelsregister-default` (+10 credits, charged only when `_realtime_mode.status` is `success`) re-fetches live register data and also returns `related_persons.current` (role `label` per person) without the feature. With realtime, `representation_scheme` and each person's `role_representation_scheme` usually hold the current rules only (`history` is `[]`) and can be null for some companies; `registration.court` stays the court name. Realtime persons have `start_date`/`end_date` null and their own person `entity_id`s (not interchangeable with the stored profile's), and the request may take much longer (set a client timeout of at least 120 s). Adding `feature=related_persons` (+2) keeps the live `current` list and adds the `past` list from the stored profile (with different person ids); `publications` (+1) works as usual. Base cost 5 credits, charged only on a successful response. The base payload always includes `capital` - registered capital as `{current, history}`, where `current` carries `amount`, `currency` and `kind` (e.g. STAMMKAPITAL, GRUNDKAPITAL, LIABILITY_SUM (Haftsumme of a cooperative), CONDITIONAL; open enum, accept unknown values) and each `history` entry carries `value`, `effective_from` and `effective_to` (null while in force). A history entry's `value.change_amount` (`{amount, currency}`) is the amount named in the register entry: it is unsigned and does not always match the difference between two consecutive amounts, so derive increases and decreases from the amounts themselves. Entities without registered capital, such as partnerships, return `current: null` and an empty `history`. - Parameters: `q` (query, required, string), `feature` (query, list of financial_kpi|balance_sheet_accounts|profit_and_loss_account|related_persons|publications|news|insolvency_publications|annual_financial_statements|annual_financial_statements__html|shareholders|shareholders_deep|ubos|shareholdings|mergers_and_acquisitions|website_content|network), `ai_search` (query, on-default), `realtime_mode` (query, handelsregister-default), `financial_statement_type` (query, auto|annual|consolidated, default auto), `financial_years` (query, integer, 1-30), `Idempotency-Key` (header, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Responses: 200, 401, 402, 403, 404, 408, 422, 429, 500. - `GET /api/v1/fetch-person` - person profile merging register data with AI web evidence. Requires `person_q` and `organization_q` (a company where the person holds or held a register role; min 2 chars each, else 422 `validation_failed`) and an active subscription on the Plus, Pro and Max plans (otherwise 403 `subscription_required`, checked first; top-up credits alone are not enough). 15 credits base (AI included); optional `features=shareholdings` (comma-separated or repeated) +5 credits, charged only when holdings are returned. 404 (not charged) when no person can be confidently linked to that company. Often takes 10-30 seconds. - Parameters: `person_q` (query, required, string, at least 2 chars), `organization_q` (query, required, string, at least 2 chars), `features` (query, list of shareholdings|network), `Idempotency-Key` (header, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Responses: 200, 401, 402, 403, 404, 408, 422, 429, 500. - `GET /api/v1/fetch-document` - official register documents. `company_id` = the 32-hex `entity_id`, not a name (400 otherwise); `document_type` (case-sensitive): `AD` current excerpt (PDF), `CD` chronological excerpt (PDF), `SI` structured register content (XJustiz XML), `shareholders_list` (PDF, GmbH/UG only), `articles_of_association` (PDF). The 200 body is the file itself (`Content-Type` application/pdf or application/xml; save the bytes), with cost and balance in the headers `X-Credits-Charged` / `X-Credits-Remaining`. 15 credits, charged only when the file is delivered; 5 requests/min. Optional `async=true`: if the document is not ready, 202 with `Retry-After: 20` at no charge - repeat the same request to get the file. Errors (none charged): 404 this document does not exist for the company, 415 the register has it only as TIFF, 502/503/504 register problems (503/504 carry `Retry-After`; retry later). A document fetched within the last 24 hours is returned as of that fetch (date in the filename). - Parameters: `company_id` (query, required, string, pattern `^[a-fA-F0-9]{32}$`), `document_type` (query, required, AD|CD|shareholders_list|articles_of_association|SI), `async` (query, boolean, default false), `Idempotency-Key` (header, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Responses: 200, 202, 400, 401, 402, 403, 404, 415, 422, 429, 500, 502, 503, 504. - `GET /api/v1/signals` - list normalized company changes. Accepted parameters, exhaustively: `topics`, `organization_ids`, `from`, `to`, `cursor` - any other parameter is rejected, not ignored: 422 `INVALID_REQUEST` with `invalid_params: {"": ["Unknown Signals parameter."]}` (only the first unknown key is reported). `topics` takes the case-sensitive UPPER_SNAKE codes from the catalog - `NEW_REGISTRATIONS`, `MASTER_DATA_CHANGES`, `CLOSURES`, `ROLE_HOLDER_CHANGES`, `CAPITAL_CHANGES` (every plan), `INSOLVENCIES` (Pro and Max), `TRANSFORMATIONS` (Max) - repeatable as `topics=A&topics=B`, `topics[]=`, or comma-separated; omitting it returns only the plan-accessible topics, never all of them - the five base topics on any plan (no subscription and Plus included), `INSOLVENCIES` additionally on Pro, `TRANSFORMATIONS` additionally on Max - silently, with no warning and `filters.topics: []` either way. Naming a topic above your plan returns 403 `PLAN_REQUIRED` (0 credits). `organization_ids`: at most 5 values, each matching `[A-Za-z0-9._~-]{1,128}`. `from`/`to`: inclusive bounds on the announcement date (`event.announced_on`, not `occurred_on`); `YYYY-MM-DD` (a bare `to` covers the whole day) or a timezone-naive `YYYY-MM-DDTHH:MM:SS[.ffffff]` - a trailing `Z` or a numeric offset such as `+02:00` is rejected with 422 - and `to` must be the same as or later than `from`. Ordering is fixed (newest announcement date first). Response: `{signals[], pagination{mode, limit, returned, has_more, next_cursor}, filters{topics, organization_ids}, warnings, meta}`; each `signals[]` item has `event` (id, topic, topic_name, occurred_on, announced_on, date_basis, optional type/type_name), `organization`, `parties` and `source`. Pagination is cursor-only and 20 is a maximum, not a guarantee: short and even empty pages with `pagination.has_more: true` are normal, so keep paging while `has_more` is true and stop only when `next_cursor` is absent. Delivery is at-least-once - de-duplicate by `signals[].event.id`. Send `next_cursor` back unchanged with a byte-identical filter set (`cursor` is opaque, max 8192 characters); changing any filter mid-pagination, `organization_ids`/`from`/`to` included, is unsupported: it usually fails with 422 `INVALID_CURSOR` but can also silently return a wrongly-offset page, so start a new query without a cursor instead. `event.topic` is one of the seven filterable codes or `OTHER` (`OTHER` cannot be used as a filter value and is not plan-gated). `event.type` is a finer-grained type released per signal and is an OPEN ENUM: currently only role-holder values (`ROLE_HOLDER_ENTRY`, `ROLE_HOLDER_EXIT`, `ROLE_HOLDER_TRANSITION`, `ROLE_HOLDER_CHANGE`; `AUTHORITY_CHANGE` is defined in the spec but not emitted today), more will be released over time, so treat unknown values as valid and fall back to `event.topic`. It is absent - omitted, never null - on every signal without a released type, which is most of them today, and `event.type_name` (localized de/en label object) appears only alongside `event.type`. Neither is a filter: filtering is by `topics` only. Other errors: 402 `INSUFFICIENT_CREDITS`, 503 `SIGNALS_UNAVAILABLE`, 403 `UNAUTHORIZED` (e-mail not verified or account blocked). 20 credits per successful page, an empty page included. Rate limit: 60 requests per minute per account, shared with search-organizations and fetch-document (the catalog and detail calls count too). - Parameters: `cursor` (query, string, 1-8192 chars), `topics` (query, list of NEW_REGISTRATIONS|MASTER_DATA_CHANGES|CLOSURES|ROLE_HOLDER_CHANGES|CAPITAL_CHANGES|INSOLVENCIES|TRANSFORMATIONS), `organization_ids` (query, list of string, 1-128 chars, pattern `^[A-Za-z0-9._~-]+$`, at most 5 values), `from` (query, string, at most 32 chars, pattern `^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?)?$`), `to` (query, string, at most 32 chars, pattern `^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?)?$`). - Responses: 200, 401, 402, 403, 422, 429, 503. - `GET /api/v1/signals/catalog` - discover the stable public Signals vocabulary and supported options. Always lists all seven topics with their `tier` (`ALL`, `PRO` or `MAX` - never null) regardless of the caller's plan, plus `capabilities.page_size` 20 and `capabilities.pagination: ["CURSOR"]`. It never exposes or proxies source-system classifications. Accepts no query parameter whatsoever: any one is rejected with 422 `INVALID_REQUEST`, detail `The catalog endpoint does not accept query parameters.` and no `invalid_params` member. Free (0 credits), never 402, and served even at a zero credit balance. - Responses: 200, 401, 403, 422, 429, 503. - `GET /api/v1/signals/{signalId}` - retrieve one Signal by opaque ID; returns `{"signal": {...}, "meta": {...}}`. Query parameters are not merely unnecessary, they are rejected: any one yields 422 `INVALID_REQUEST` / `Unknown Signals parameter.`. `signalId` must match `[A-Za-z0-9][A-Za-z0-9._~-]{0,254}`; a value that misses the pattern never reaches the API and returns a generic 404 (`{"message": "An error occurred while processing your request.", "error": "Not Found"}` with `Accept: application/json`, otherwise an HTML page) instead of `application/problem+json`, while an unknown or blocked ID returns 404 `SIGNAL_NOT_FOUND`. The plan gate is applied after the lookup, so a Pro- or Max-only Signal returns 403 `PLAN_REQUIRED` (0 credits); events outside the seven topics resolve to `event.topic: "OTHER"` and are readable on any plan. 20 credits on success. - Parameters: `signalId` (path, required, string, 1-255 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$`). - Responses: 200, 401, 402, 403, 404, 422, 429, 503. Token management (API-key auth, 10/min; Bearer tokens are not accepted here): - `POST /api/v1/auth/tokens/create` - create a Bearer token with your API key (body: see Authentication); the response carries no token id, so find it by name with `GET /api/v1/auth/tokens` before revoking. Free. - Body: JSON with `token_name` (required, string, at most 255 chars), `abilities` (list of string, at most 255 chars), `expires_at` (string, date-time). - Auth: `x-api-key` header or `api_key` query parameter only. - Responses: 201, 401, 403, 429, 500. - `GET /api/v1/auth/tokens` - all Bearer tokens of the account, newest first, including the admin token and the access tokens of connected AI apps. Free. - Auth: `x-api-key` header or `api_key` query parameter only. - Responses: 200, 401, 403, 429. - `DELETE /api/v1/auth/tokens` - revokes every Bearer token, including the admin token and tokens of connected apps (MCP clients must sign in again); free. - Auth: `x-api-key` header or `api_key` query parameter only. - Responses: 200, 401, 403, 429. - `DELETE /api/v1/auth/tokens/{tokenId}` - revokes one Bearer token, the admin token and connected-app tokens included. Free. - Parameters: `tokenId` (path, required, integer). - Auth: `x-api-key` header or `api_key` query parameter only. - Responses: 200, 401, 403, 404, 429. ## Account endpoints (free, 0 credits, 30/min) Read-only self-service endpoints for building your own dashboards and admin tooling. Header or Bearer auth only - the `?api_key=` query parameter is rejected with 400 on these routes. Bearer tokens need the `account:read` ability. - `GET /api/v1/account` - profile summary of the authenticated account (id, name, email, email_verified, language, plan, member_since). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `GET /api/v1/account/credits` - credit balance split into subscription/purchased, next expiring grant, per-grant breakdown. - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `GET /api/v1/account/usage` - aggregated usage for a bounded range (`from`/`to`, default current month, max 366 days; `group_by=day|month`): totals, per-endpoint breakdown, zero-filled time series. - Parameters: `from` (query, string), `to` (query, string), `group_by` (query, day|month). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `GET /api/v1/account/usage/transactions` - cursor-paginated ledger of billable requests, newest first (`endpoint` filter, `per_page` max 100, `cursor` for pagination). `endpoint` values are ledger labels (search appears as `/api/v1/search-companies`); treat them as opaque strings. - Parameters: `from` (query, string), `to` (query, string), `endpoint` (query, string), `per_page` (query, integer, at least 1, default 25), `cursor` (query, string). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `GET /api/v1/account/api-keys` - active API keys, newest first, masked (last 8 chars), with `is_current`, last-use timestamp and `usage_last_30d`. - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `POST /api/v1/account/api-keys` - create an API key (10/min). Returns the new key in full once; at most 25 active keys. Requires the admin token (a Bearer token with the `account:keys` ability, created on the account's API-keys page); an API key can never create or revoke API keys, and tokens it creates via /v1/auth/tokens/create never get `account:keys`. - Auth: Bearer token only. - Responses: 201, 401, 403, 422, 429. - `DELETE /api/v1/account/api-keys/{apiKeyId}` - immediately revoke an API key (10/min); needs the admin token like creating one. - Parameters: `apiKeyId` (path, required, integer). - Auth: Bearer token only. - Responses: 200, 401, 403, 404, 429. - `GET /api/v1/account/subscription` - current subscription state incl. plan, status, period bounds, and included features (`null` without one). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. ## fetch-organization features (cost in credits; charged only when data is returned) - `financial_kpi` (1) - yearly financial metrics, one row per year, newest first; base fields on every plan: year (calendar year in which the fiscal year ends), employees, revenue, net_income, active_total, material_expenses, personnel_expenses (expenses carry the sign printed in the filing, so compare absolute values). The Pro and Max plans receive additional balance-sheet, income-statement and ratio fields in the same rows at the same 1-credit cost. On every plan each row ends with `_provenance`, the statement the year's figures come from: `statement_type` (`Jahresabschluss` = the company's own annual accounts, `Bilanz` = a balance sheet published on its own, `Konzernabschluss` = consolidated group accounts, null = market data of a listed company), `period_start` / `period_end` (the fiscal period as printed, YYYY-MM-DD or null), `exempt_subsidiary` (true = the filing publishes the consolidated accounts of a parent's group, so the year's figures are that group's, not the company's own) and `parent_organization` (`{entity_id, name}` of that parent, `entity_id` null when not uniquely identified; null unless `exempt_subsidiary` is true). Compare years only within one `statement_type`. - `publications` (1) - organization-profile publication history returned under `history`; distinct from the cross-company `/signals` feed - `related_persons` (2) - current & past directors/officers with roles and tenures; `label` is the machine-readable role (MANAGING_DIRECTOR, BOARD, BOARD_CHAIR, PROCURA, FULLY_LIABLE_PARTNER, LIMITED_PARTNER, LIQUIDATOR, ...; schema RelatedPersonRoleLabel). - Signals name two of these roles differently: BOARD = BOARD_MEMBER, PROCURA = AUTHORIZED_SIGNATORY. - `balance_sheet_accounts` (3) - hierarchical balance sheets, one document per year, newest first: `year`, the tree `balance_sheet_accounts` (nodes `{name: {de, en, in_report}, value, children}`, `en` only for known accounts; roots Aktivseite and Passivseite, identify them by `name.de`) and `_provenance` (same fields as in `financial_kpi`). Max plan only: energy utilities also get `activity_statements`, the balance sheets they publish per regulated activity (activity statements, section 6b EnWG), each `{activity: {name: {de, en, in_report}}, balance_sheet_accounts, _provenance}` with `statement_type` Taetigkeitsabschluss (the JSON value carries the umlaut; escaped: `T\u00e4tigkeitsabschluss`); absent on all other plans and when the filing has none; same 3 credits. Activities are not a breakdown of the company totals. - `profit_and_loss_account` (3) - hierarchical P&L statements, one document per year, newest first: `year`, the tree `profit_and_loss_accounts` (same node shape; the top level mixes positions and printed subtotals, so never sum it; expenses carry the sign printed in the filing) and `_provenance`. Max plan only: energy utilities also get `activity_statements` with each activity's P&L under `profit_and_loss_accounts`, in the same item shape; absent on all other plans and when the filing has none; same 3 credits. - `insolvency_publications` (5) - insolvency court publications - `annual_financial_statements` (5) - full annual reports as Markdown - `annual_financial_statements__html` (5) - full annual reports as HTML - `shareholders` (5, Beta) - shareholder list with contributions and ownership ratios - `shareholdings` (5, Beta) - the company's holdings in other companies - `news` (10) - recent news articles with source and URL - `ubos` (10, Beta) - ultimate beneficial owners incl. ownership paths and unresolved owners - `mergers_and_acquisitions` (20, Beta) - M&A transactions (mergers, splits, enterprise agreements), control relationships, and summary - `network` (25, Beta) - relationship graph of the entity: nodes (ORGANIZATION|PERSON, with depth and is_root) and connections (GROUP|ROLE|OWNERSHIP, localized role labels, start/end dates, is_current, ownership details on OWNERSHIP). Also available on fetch-person. Only on the Pro and Max plans (the key is ignored on other plans). Charged only when at least one connection is returned. Responses with network also carry a top-level `management` list (current direct relations, no extra charge). - `shareholders_deep` (80) - who holds the company, read from all its shareholder lists (Gesellschafterlisten), the founding document, or for partnerships the partners registered in the commercial register. The block has `record` (date and kind of the current filing), `share_capital`, `entries` (the current holders, each with `role` SHAREHOLDER, LIMITED_PARTNER, FULLY_LIABLE_PARTNER, PARTNER, PROPRIETOR or OWNER, `ownership` with percentage, nominal amount and share numbers, and `since`), `history` (the earlier filings, newest first; not the top-level publications `history`) and `changes` (who joined or left and whose percentage changed with the latest filing). Holders are typed (ORGANIZATION, PERSON, JOINT) and carry an `entity_id` when identified. `null` when no current ownership information is available (typical for an AG or SE; also when only older records exist; `null` does not prove that the company has no shareholders). Enum values are case-sensitive; new values may be added. Max plan only (the key is ignored on other plans and nothing is charged). Charged only when the current filing names at least one holder. Full field reference: schema `ShareholdersDeep` in the OpenAPI spec. - `website_content` (0, requires AI mode) - company website as LLM-optimized Markdown Statement type and fiscal years of the financial features (`financial_kpi`, `balance_sheet_accounts`, `profit_and_loss_account`, `annual_financial_statements`, `annual_financial_statements__html`), same prices: - `financial_statement_type=auto|annual|consolidated` - `auto` (default): each feature picks its own type, so one response can mix single-entity and group figures (check `_provenance.statement_type`). `annual`: single-entity statements only (Jahresabschluss, also Bilanz filings). `consolidated`: group statements only (Konzernabschluss, including ESEF; market data for listed groups). A forced type never falls back to the other type: a company without such a statement returns `[]` for the feature, which is not billed. - `financial_years=1..30` - the N newest fiscal years, counted within the chosen type. Without it: all years, and the 5 newest filings for the report documents; with it, every filing of those years (at most 2N + 5). `annual_financial_statements__html` can get very large with many years. - An invalid value of either parameter returns HTTP 422 (`error: validation_failed`) before anything is charged. Example: `GET /api/v1/fetch-organization?q=&feature=financial_kpi&feature=balance_sheet_accounts&financial_statement_type=consolidated&financial_years=3` ## Billing semantics - Every successful fetch-organization request: 5 credits base + per-feature costs, but a feature that returns no data costs nothing. The response `meta.request_credit_cost` always shows the real charge; `meta.credits_remaining` the balance. - Failed requests charge 0 credits, except the +20 AI surcharge when `ai_search=on-default` and the lookup ran (404, 500, other data-source errors); 408 Request timeout and refusals before the lookup (401, 402, 403, 422, 429) are always free. Realtime (+10) is charged only when `_realtime_mode.status` is `success`. - search-organizations: 1 credit per page, an empty page and a page for an unknown filter value included; refusals and errors (400, 403, 422, 5xx) cost 0. - fetch-person and fetch-document are charged only when the profile or the file is delivered. - Safe retries: paid reads (search-organizations, fetch-organization, fetch-person, fetch-document) accept an optional `Idempotency-Key` header (1-128 chars `[A-Za-z0-9._:-]`, starting alphanumeric; a malformed key is ignored). Within 24 h the same request is charged once: a repeat with the same key and parameters returns the result again for 0 credits (`Idempotency-Status: replayed`; `meta.request_credit_cost: 0` on the JSON endpoints, `X-Credits-Charged: 0` on fetch-document); the first charge carries `Idempotency-Status: created`. Only a delivered result binds the key; the same key with other parameters returns 422 `idempotency_key_reused`. - Signals: every successful list, detail, or pagination page costs exactly 20 credits - an empty page included - and every page is a separate charge; the Signals catalog is always free. No non-2xx Signals response is ever charged: validation (422), authentication (401/403), plan-required (403), insufficient credits (402), not-found (404), rate limit (429), and temporary source failures (503) all cost 0. Credits are deducted only after the result is ready; if the deduction itself fails you get 402 `BILLING_FAILED` and no data. Signals takes no `Idempotency-Key`. Signals responses from the API carry `Cache-Control: private, no-store`, `X-Credits-Charged` and `X-Request-Id` - a route-pattern 404 is the generic API 404 (JSON only with `Accept: application/json`) without those headers and without a problem body - and raw source taxonomy is never returned. A throttled Signals 429 is not `application/problem+json`: its body is the general API 429 `{"error": "Too many requests", "message": "Rate limit exceeded. Retry after N seconds.", "retry_after": N}` (whatever the Accept header), with `Retry-After` and `X-RateLimit-Limit`/`-Remaining`/`-Reset`; it carries `Cache-Control: no-cache, private` and neither `X-Credits-Charged` nor `X-Request-Id`. Wait `retry_after` seconds before retrying. ## Errors - Send `Accept: application/json`; branch on the HTTP status and the machine code in `error`; messages are English and meant for humans. In production an /api request without `Accept: application/json` gets an HTML page for a generic 404, 405 or 500. - Signals errors are `application/problem+json` with the machine code in `code` (plan gate: `PLAN_REQUIRED`). - 400 invalid parameters (search-organizations: a bad parameter, or neither `q` nor `filters`; fetch-document: a bad `company_id` or `document_type`; also `?api_key=` on `/api/v1/account/*`). - 401 missing or invalid credential. - 402 balance below the request's maximum possible cost; body `{"meta": {"message": ..., "request_credit_cost": , "credits_remaining": ...}}`. - 403 e-mail not verified (`{"error": ..., "email_verified": false, "verification_required": true}`), account blocked, plan required (`subscription_required`, e.g. fetch-person or the plan-gated search filters) or a missing token ability. - 404 company, person or document not found (no charge, apart from the AI surcharge described above). - 408 the data source was too slow (nothing charged, AI surcharge included). - 409 and 428: Monitoring idempotency (see the Monitoring section). - 415 fetch-document: the register has this document only as TIFF. - 422 invalid value: `validation_failed` (fetch-organization `financial_statement_type`/`financial_years`, fetch-person parameters shorter than 2 chars), `idempotency_key_reused` (Idempotency-Key reused with other parameters), search filter or sort errors listed in `detail[]`. - 429 rate limit (see Limits). - 5xx (temporary; no charge apart from the AI surcharge described above): 500 data source unreachable (search-organizations also for `skip` >= 10000), 502/503 source problems, 504 on fetch-document (register timeout, retry after `Retry-After`). - Retry 408, 429 (after `Retry-After`) and 5xx with backoff; fix the request for 400, 401, 402, 403, 404 and 422. ## Limits - Rate limits per account and minute; all keys and tokens of an account count together, and rejected requests count too: fetch-organization 60 and fetch-person 60 (each its own bucket); search-organizations and fetch-document share one bucket of 60, fetch-document additionally 5/min; account endpoints 30 (15 per IP without valid credentials); `/api/v1/auth/tokens*` and API-key, monitor and webhook writes 10; webhook verify, test and rotate-secret 6. - Signals list, catalog and detail calls count toward the shared search-organizations/fetch-document bucket and also stop at 120 seconds. - A 429 (rate limit) on any endpoint is plain JSON, not application/problem+json: `{"error": "Too many requests", "message": "Rate limit exceeded. Retry after 19 seconds.", "retry_after": 19}` with the headers `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` (and `X-RateLimit-Reset`), whatever the Accept header. It carries no `X-Credits-Charged` and costs nothing. Wait `Retry-After` seconds before retrying. - fetch-organization, fetch-person and fetch-document stop at 120 seconds (408, nothing charged); set your client timeout to at least 120 s. ## Compatibility - /v1 evolves additively: new fields, nested objects and enum values of lists marked extensible appear without notice; nothing is removed, renamed or changed in type or meaning without a new API version. Ignore unknown fields, treat unknown enum values as a generic case, read fields by name (key order is not stable), and expect `null` or `[]` for empty values. ## AI agents & MCP - MCP server (Model Context Protocol): `https://mcp.handelsregister.ai/mcp` - read-only tools, grouped by data product below. Each call costs the same credits as the matching REST request. Auth: `X-API-Key: ` or `Authorization: Bearer `, or OAuth 2.1 for interactive clients (ChatGPT, Claude, Cursor). Transport: Streamable HTTP (POST /mcp); no SSE endpoint. - Account: `get_account_status` (plan, credit balance, unlocked data; free). - Company profile (fetch-organization: 5 credits base + feature): `get_company_overview`, `get_company_snapshot` (overview, financial KPIs and current management in one call), `get_company_features` (several features, one base), `get_related_persons`, `get_shareholders`, `get_ubos`, `get_shareholdings`, `get_financials`, `get_balance_sheet`, `get_profit_and_loss`, `get_annual_financial_statements` (Markdown), `get_annual_financial_statements_html`, `get_mergers_and_acquisitions`, `get_publications`, `get_insolvency_publications`, `get_news`, `get_website_content` (always with AI enrichment, +20). - Search and finders (1 credit per page): `search_organizations`, `search_organizations_advanced`, `find_companies_by_industry`, `find_companies_by_financials`, `find_companies_near`, `find_newly_registered_companies`, `find_recently_changed_companies`, `find_related_companies`, `find_companies_by_person` (owners: Pro and Max plans), `find_companies_by_ownership` (Pro and Max plans), `find_companies_by_management` (Pro and Max plans), `find_companies_in_insolvency` (Pro and Max plans), `get_search_filter_reference` (free), `find_industry_codes` (free; WZ 2025 codes from words). - Signals feeds (20 credits per page, empty pages included): `get_recent_new_registrations`, `get_recent_management_changes`, `get_recent_capital_changes`, `get_recent_master_data_changes`, `get_recent_company_closures`, `get_recent_insolvency_events` (Pro and Max plans), `get_recent_mergers_and_transformations` (Max plan), `get_recent_company_changes` (up to 5 companies), `get_signal_details`. - Person and documents: `fetch_person` (15 credits, +5 with shareholdings; Plus, Pro and Max plans), `fetch_document` (15 credits). - Company tools take `ai_search` (+20) and `realtime` (+10). Not on MCP (use REST): `shareholders_deep`, `financial_statement_type`, `financial_years`. - Claude Code: `claude mcp add --transport http handelsregister https://mcp.handelsregister.ai/mcp --header "X-API-Key: YOUR_API_KEY"` - OAuth 2.1 authorization server with dynamic client registration (RFC 7591) and PKCE: discovery at `https://handelsregister.ai/.well-known/oauth-authorization-server`; protected-resource metadata at `https://mcp.handelsregister.ai/.well-known/oauth-protected-resource`. Use PKCE with S256. Scopes: `mcp`, `api`, `offline_access`; a client that requests none gets `mcp` and `offline_access`. Issued access tokens also work on the REST API as Bearer tokens. A token with only scope `mcp` works on the data endpoints but not on `/api/v1/account/*` (403); request scope `api` for those. ## SDKs - Python: `pip install handelsregister` - https://github.com/Handelsregister-AI/handelsregister - Node.js: `npm install handelsregister` - https://github.com/Handelsregister-AI/handelsregister-js ## Organization Monitoring and outbound webhooks Monitoring watches companies selected by the account and sends new normalized commercial-register changes through signed webhooks. It is an independent product from the cross-company Signals search API, although both intentionally use the same topic vocabulary, `organization.signal.detected`, `data.signal`, and the Signal-detail link. The Monitoring management API is under `/api/v1/account`. Account routes accept only `x-api-key` or `Authorization: Bearer ...`; `?api_key=` is rejected. Reads are free and require `account:read` on Bearer tokens. Monitor mutations and endpoint verification/test/delivery retry accept API keys; Bearer tokens need `account:read` plus the literal `monitoring:manage` ability. Endpoint create, secret rotation, enable/disable, and archive require a Bearer token with `account:read` plus literal `account:keys`; API keys cannot perform them (a plain API key gets 403). Every mutation below requires `Idempotency-Key` (1-128 characters: a letter or digit, then letters, digits, `.`, `_`, `:`, `-`); missing -> 428, malformed -> 400. The first non-5xx result has `Idempotency-Status: created`; an exact retry within 24 hours replays the same status and body (including a one-time secret) with `replayed`, errors included, so use a new key for a new attempt. Same key with different parameters -> 409 `idempotency_conflict`; while the first request runs -> 409 `idempotency_in_progress`. Endpoint verify/test perform network I/O: an in-progress 409 means the API cannot prove whether the receiver saw the request; stop automatic retries and contact support, do not retry later or invent a new key. A 503 `temporarily_unavailable` starts nothing and does not use the key. Limits: all account routes 30 requests/min per account; management writes additionally 10/min, verify/test/rotate-secret 6/min (counted together with the other writes). Endpoint verify: at most 6 attempts per endpoint per hour. ### Monitor endpoints - `GET /api/v1/account/monitoring/pricing` - free current policy, topic entitlement, and fresh-cycle estimate; default interval 30. Returns `pricing` (`policy_version`, `cycle_days`, `included_runs`, `cycle_minimum_credits`, `credits_per_run`, `estimated_runs`, `estimated_credits`) and `entitled`. - Parameters: `poll_interval_days` (query, integer, 1-30, default 30). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `GET /api/v1/account/monitors` - newest 100 non-archived monitors; no cursor. - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `POST /api/v1/account/monitors` - body: `entity_id` (the organization entity_id; only its format is checked, max 128 chars), optional `label` (max 200 chars), integer `poll_interval_days`, non-empty distinct `endpoint_ids`. The cycle is priced at the rate in force when it opens; the `pricing_policy_version` that applied is returned on the monitor and its billing cycle, and is not an input. Exact endpoints must be owned, active, verified and unarchived; the account needs at least one accessible Monitoring topic. One live monitor per `entity_id` (409 `duplicate_monitor`); at most 50 live monitors (422 `monitor_limit`) and 50 creations per rolling 24 hours, archived ones included (429 `creation_rate_limited` with `Retry-After`). Returns 202 `initializing`, queues a free baseline, and charges 0 in the request. - Parameters: `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Body: JSON with `entity_id` (required, string, 1-128 chars, pattern `^[A-Za-z0-9._~-]+$`), `label` (string, at most 200 chars), `poll_interval_days` (required, integer, 1-30), `endpoint_ids` (required, list of string, pattern `^wep_[a-z0-9]{26}$`, 1-10 values). - Auth: `x-api-key` header or Bearer token only. - Responses: 202, 400, 401, 403, 409, 422, 428, 429, 503. - `GET /api/v1/account/monitors/{publicId}` - monitor, active billing-cycle summary or null, newest 20 runs. Known archived history remains readable. - Parameters: `publicId` (path, required, string, pattern `^mon_[a-z0-9]{26}$`). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 429. - `PATCH /api/v1/account/monitors/{publicId}` - body `{"poll_interval_days": 1..30}` (the pricing policy is resolved server-side, not an input). Prospective only: an active monitor's next check is due `poll_interval_days` from now; the running cycle keeps its frozen price and included checks, the new cadence price applies from the next cycle; no refund. Works in every non-archived state (archived -> 422 `not_resumable`). Cannot change label or destinations. - Parameters: `publicId` (path, required, string, pattern `^mon_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Body: JSON with `poll_interval_days` (required, integer, 1-30). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 422, 428, 429. - `DELETE /api/v1/account/monitors/{publicId}` - archive, never hard-delete. - Parameters: `publicId` (path, required, string, pattern `^mon_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 428, 429. - `POST /api/v1/account/monitors/{publicId}/pause` - only active transitions to `paused_user`; every other state is a 200 no-op. In particular, pausing `initializing` does not stop its baseline, activation, or its possible cycle charge; archive it to stop before activation. No refund. - Parameters: `publicId` (path, required, string, pattern `^mon_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 428, 429. - `POST /api/v1/account/monitors/{publicId}/resume` - no body; the current price sheet is applied server-side. Requeues an incomplete baseline for 0. A completed baseline rechecks policy, endpoint, and at least one accessible topic before funding; it reuses a live funded cycle for 0 or can charge a new cycle price. Inspect `meta.activated`, `baseline_queued`, and `billing`. - Parameters: `publicId` (path, required, string, pattern `^mon_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Body: JSON, optional. - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 422, 428, 429, 503. Monitor states: `initializing`, `active`, `paused_user`, `paused_configuration`, `paused_entitlement`, `paused_billing`, `error`, `archived`. A monitor has no per-topic filter. Every account can receive `NEW_REGISTRATIONS`, `MASTER_DATA_CHANGES`, `CLOSURES`, `ROLE_HOLDER_CHANGES`, and `CAPITAL_CHANGES`; `INSOLVENCIES` needs a Pro or Max plan; `TRANSFORMATIONS` needs the Max plan. The scanner still observes all seven topics for durable baseline/deduplication, but only topics accessible under the account's current plan may be released. A Signal in a topic outside the current plan is never delivered, not even after an upgrade. Upgrading affects only observations first seen after the upgrade: already baselined or plan-suppressed history is not replayed. Downgrading leaves the monitor active and continues accessible topics; already released messages and eligible retries are immutable. `paused_entitlement` remains a defensive state for an account with no accessible topics. ### Billing and polling Per monitor, the asynchronous all-topic baseline is free and suppresses historical observations. Only after a complete baseline, including one completed with non-fatal warnings, does activation attempt the first cycle charge. A prospective rolling 30-day cycle is a set price per cadence: daily 50, every 3 days 40, weekly 20, monthly 10 credits. An interval with no listed price is billed at the next more frequent cadence, so every 4 days costs the same as every 3. The price covers the checks that cadence forecasts (`ceil(30 / interval)`); each further complete successful check costs 2. A complete successful check costs the same with zero or many eligible/new signals. Failed, partial, superseded, or unfunded checks add no run charge; the cadence price is not refunded. Extra-run affordability is checked before scanning and the debit settles exactly once before notifications are released. A funded cycle keeps its frozen policy; after a repricing, a renewal parks the monitor as `paused_billing` (reason `pricing_consent_required`); call resume to accept the current price and reactivate it. The price is not rechecked at every mid-cycle settlement. Renewal while active is prospective. Pause/archive gives no refund; resume within an unexpired funded cycle does not charge the cadence price again. Missed time is coalesced into one overlap scan billed like any other complete successful check, not back-billed per missed slot. For a succeeded run, `events_new` is the distinct count of plan-eligible new notifications released by that run; multiple endpoints do not multiply it. A scheduled continuation may show accumulated progress. An unfunded failed run can show candidates that remained undelivered, so do not treat `events_new` as an unconditional delivery count. ### Webhook management and history - `GET /api/v1/account/webhook-endpoints` - all non-archived endpoints (maximum 10); URLs and custom headers are masked. - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. - `POST /api/v1/account/webhook-endpoints` - `name` (max 120), public HTTPS/443 `url` (max 2048), optional write-only `headers`; returns 201 pending endpoint plus one-time `whsec_` signing secret. At most 10 active endpoints; name, URL and headers cannot be changed later. - Parameters: `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Body: JSON with `name` (required, string, 1-120 chars), `url` (required, string, uri, 1-2048 chars), `headers` (object). - Auth: Bearer token only. - Responses: 201, 400, 401, 403, 409, 422, 428, 429. - `POST /api/v1/account/webhook-endpoints/{publicId}/verify` - only `pending_verification` sends a synchronous signed challenge; the receiver must return 2xx and echo `data.challenge` in `webhook-verification`. Failure returns 422 with `verified:false`. An already verified or disabled endpoint returns its stored verification state without network I/O and does not become enabled; call `enable` separately. - Parameters: `publicId` (path, required, string, pattern `^wep_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 422, 428, 429, 503. - `POST /api/v1/account/webhook-endpoints/{publicId}/rotate-secret` - returns a new one-time secret. Normal deliveries, tests, and samples carry signatures for current and predecessor secrets for seven days; verification challenges use only the current secret. - Parameters: `publicId` (path, required, string, pattern `^wep_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 428, 429. - `POST /api/v1/account/webhook-endpoints/{publicId}/test` - synchronous signed test attempt. HTTP 200 means the attempt was recorded, not necessarily delivered; inspect `delivery.status`. - Parameters: `publicId` (path, required, string, pattern `^wep_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 428, 429, 503. - `POST /api/v1/account/webhook-endpoints/{publicId}/{state}` - `state` = `enable` or `disable`: enable requires verification; disable parks monitors that lose their last endpoint. - Parameters: `publicId` (path, required, string, pattern `^wep_[a-z0-9]{26}$`), `state` (path, required, enable|disable), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 428, 429. - `DELETE /api/v1/account/webhook-endpoints/{publicId}` - archive endpoint and subscriptions. - Parameters: `publicId` (path, required, string, pattern `^wep_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 428, 429. - `GET /api/v1/account/webhook-deliveries` - newest 50 delivery summaries; no cursor/detail. - Parameters: `endpoint` (query, string, pattern `^wep_[a-z0-9]{26}$`). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 429. - `POST /api/v1/account/webhook-deliveries/{publicId}/retry` - retry an eligible retained failed delivery with the same message id/body. The public `delivery.attempts` schedule counter resets to 0; append-only audit attempt numbers remain monotonic. - Parameters: `publicId` (path, required, string, pattern `^del_[a-z0-9]{26}$`), `Idempotency-Key` (header, required, string, 1-128 chars, pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`). - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 404, 409, 428, 429, 503. - `GET /api/v1/account/webhook-events` - newest 50 summaries; no body/detail/replay endpoint. - Auth: `x-api-key` header or Bearer token only. - Responses: 200, 400, 401, 403, 429. Production endpoint URLs must use HTTPS port 443, contain no userinfo, fragment, or IP-literal host, resolve only to public addresses. Redirects are never followed. Custom header values and full URLs are encrypted/write-only; transport, forwarding, and `webhook-*` names are reserved. ### Receiver contract Event types: `organization.signal.detected` (new monitored Signal), `organization.signal.sample` (historical sample), `endpoint.test` (signed endpoint test), `endpoint.verification` (proof-of-control challenge). Delivery is at-least-once with no cross-event ordering guarantee. The JSON envelope is `{id,event_id,type,timestamp,schema_version:1,data}`; verification omits `event_id`. Live type `organization.signal.detected` carries `data.monitor`, a normalized `data.signal`, and `data.links.signal`; it never carries `data.sample`. Heavy `details` and `register_entry` fields may be removed with `data.truncated=true`. `data.links.signal` points to the independent Signals detail API. The webhook itself does not call or charge that API. Following the link is a separate authenticated request, costs 20 credits only on success, and can return 401, 402, 403 `PLAN_REQUIRED`, 404, or 503. Test and UI sample types are `endpoint.test` and `organization.signal.sample`. A sample always sets `data.sample=true`; a detected event never does. Sample discovery is a bounded scan of at most the last 48 months, returns at most 10 current-plan items, and can be partial rather than exhaustive. Sending a sample is free and rechecks the current plan. Verify the exact raw request bytes before parsing. Headers are `webhook-id`, Unix-seconds `webhook-timestamp`, and `webhook-signature`. For each space-separated `v1,` candidate, compute base64(HMAC-SHA256(`webhook-id.webhook-timestamp.raw_body`, base64-decode(the `whsec_` suffix))). For normal deliveries, tests, and samples, accept either signature during the seven-day rotation grace; verification challenges use the current secret only. Deduplicate `webhook-id`. Any 2xx succeeds. 3xx redirects, ordinary 4xx, 5xx, timeouts and connection failures retry; 410 immediately exhausts the delivery and disables the endpoint. Automatic delivery has ten total attempts spread over roughly three days; configured individual retry gaps range from about five seconds to one day, with jitter. Valid `Retry-After` is honored only for 429/502/503/504 and capped at one day. Five consecutive exhausted deliveries disable an endpoint. Request timeout is 15 seconds (5-second connect); receiver responses are capped at 64 KiB. Delivery states: `withheld`, `pending`, `in_flight`, `retry_wait`, `succeeded`, `blocked_endpoint`, `exhausted`, `cancelled`. Event/message data is retained encrypted for 30 days then tombstoned; attempt audit rows are retained 90 days. Common errors: 401 authentication; 403 ability/plan/account; tenant-scoped 404; 409 stale pricing/duplicate/idempotency conflict or ambiguity; 422 request or domain validation (verification failure is a normal `verified:false` body); 428 missing idempotency key; 429 rate limit; 503 `temporarily_unavailable` (retry later). Webhook policy/business failures generally use 400 `invalid_request`. ## More - [Changelog](https://handelsregister.ai/en/changelog) - [FAQ](https://handelsregister.ai/en/faq) - [MCP server](https://handelsregister.ai/en/mcp): setup for Claude, ChatGPT, Cursor and other MCP clients - [n8n integration](https://n8n.io/integrations/handelsregisterai/) - [Pricing and plans](https://handelsregister.ai/en#pricing=plans): Plus EUR 69 (8,000 credits), Pro EUR 129 (17,000 credits), Max EUR 499 (75,000 credits) per month; a new account gets 150 start credits, valid for 30 days.