Getting Started

This guide walks through a complete German company retrieval workflow—from searching for a company to setting up ongoing monitoring.

Getting an API Key

To use the Kausate API, you'll need an API key. There are two ways to get one:

Self-serve signup: Create an account at kausate.com/signup and generate an API key from your dashboard
Get in touch: Contact us for enterprise plans or custom requirements

Once you have your API key, include it in all requests using the X-API-Key header.

Data Flow Overview

A typical integration follows this pattern:

Step	Endpoint	Use Case
Search	`POST /v2/companies/search/`	Find companies by name
Prefill	`POST /v2/companies/{id}/prefill`	Fast form pre-fill (~200ms)
Report	`POST /v2/companies/{id}/report`	Full real-time company data
Monitor	`POST /v2/monitors`	Track changes over time

Complete Example: German Company Retrieval

Search for a Company

Find the company using live search. This fetches real-time results directly from the official registry.

curl -X POST https://api.kausate.com/v2/companies/search/ \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Bundesanzeiger Verlag",
    "jurisdictionCode": "de"
  }'

Response:

{
  "orderId": "de-live-search-bundesanzeiger-verlag-20250115103000",
  "status": "completed",
  "requestTime": "2025-01-15T10:30:00Z",
  "responseTime": "2025-01-15T10:30:02Z",
  "result": {
    "type": "liveSearch",
    "searchResults": [
      {
        "kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
        "name": "Bundesanzeiger Verlag GmbH",
        "jurisdictionCode": "de",
        "identifiers": [
          {
            "type": "de_registernumber_weak",
            "value": "HRB 31248",
            "description": "Amtsgericht Köln"
          },
          {
            "type": "de_registernumber_full",
            "value": "R2201_HRB 31248"
          }
        ],
        "addresses": [
          {
            "type": "registered",
            "streetAddress": "Amsterdamer Str. 192",
            "postalCode": "50735",
            "city": "Köln"
          }
        ]
      }
    ]
  }
}

Save the kausateId for subsequent calls.

Quick Data with Prefill

For onboarding flows where speed matters, use the prefill endpoint. It returns indexed data with a real-time fallback, typically in under 200ms.

curl -X POST https://api.kausate.com/v2/companies/co_de_7KGHtucR88u2omSx3KhaoH/prefill \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"customerReference": "onboarding-123"}'

Response:

{
  "orderId": "ord_abc123",
  "status": "completed",
  "requestTime": "2025-01-15T10:30:00Z",
  "responseTime": "2025-01-15T10:30:00.180Z",
  "result": {
    "basicInformation": {
      "legalName": "Bundesanzeiger Verlag GmbH",
      "legalForm": "GmbH",
      "registrationDate": "1998-12-22",
      "addresses": [...],
      "identifiers": [...]
    }
  }
}

Prefill is optimized for speed. For comprehensive data including legal representatives and shareholders, use the report endpoint.

Full Company Report (Real-Time)

For complete company data fetched directly from the Handelsregister, use the report endpoint.

Synchronous mode (sync=true) is not recommended. Government business registries are inherently unreliable—timeouts and temporary unavailability are common. Use the asynchronous approach with webhooks (recommended) or polling using the orderId to receive results reliably.

Asynchronous request (recommended) — returns immediately with orderId:

curl -X POST https://api.kausate.com/v2/companies/co_de_7KGHtucR88u2omSx3KhaoH/report \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"customerReference": "kyc-check-456"}'

The async request returns:

{
  "orderId": "ord_xyz789",
  "customerReference": "kyc-check-456",
  "status": "running"
}

Option A: Set up a webhook (recommended) to receive results automatically:

curl -X POST https://api.kausate.com/v2/webhooks \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Results",
    "url": "https://your-server.com/webhooks/kausate"
  }'

Option B: Poll for results:

curl https://api.kausate.com/v2/orders/ord_xyz789 \
  -H "X-API-Key: your_api_key"

Completed response:

{
  "orderId": "ord_xyz789",
  "status": "completed",
  "result": {
    "sources": {
      "registrar": "Amtsgericht Köln",
      "retrievalTimestamp": "2025-01-15T10:35:00Z"
    },
    "basicInformation": {
      "legalName": "Bundesanzeiger Verlag GmbH",
      "legalForm": "GmbH",
      "capital": {
        "amount": 1000000,
        "currency": "EUR",
        "type": "share_capital"
      },
      "addresses": [...],
      "identifiers": [...],
      "businessActivities": [...]
    },
    "relationships": {
      "legalRepresentatives": [...],
      "shareholders": [...]
    }
  }
}

Synchronous mode (not recommended)

While a sync=true parameter is available, it is not recommended for production use. Government business registries experience frequent timeouts, rate limiting, and temporary outages. Synchronous requests may fail with HTTP 408 (timeout) errors even when the data would eventually become available.

curl -X POST "https://api.kausate.com/v2/companies/co_de_7KGHtucR88u2omSx3KhaoH/report?sync=true" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"customerReference": "kyc-check-456"}'

Set Up Monitoring

To track changes to a company over time, create a monitor. When changes are detected, you'll receive a webhook notification.

First, create a webhook:

curl -X POST https://api.kausate.com/v2/webhooks \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Changes",
    "url": "https://your-server.com/webhooks/kausate"
  }'

Response:

{
  "id": "wh_def456",
  "name": "Company Changes",
  "url": "https://your-server.com/webhooks/kausate",
  "status": "ACTIVE",
  "createdAt": "2025-01-15T10:40:00Z"
}

Then, create a monitor:

curl -X POST https://api.kausate.com/v2/monitors \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
    "scheduleCron": "0 8 * * *"
  }'

Response:

{
  "monitorId": "mon_ghi789",
  "kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
  "companyName": "Bundesanzeiger Verlag GmbH",
  "scheduleCron": "0 8 * * *",
  "checkCount": 0,
  "isActive": true,
  "createdAt": "2025-01-15T10:45:00Z"
}

The monitor will check for changes daily at 8:00 AM and send webhook notifications when changes are detected.

Choosing the Right Endpoint

Need	Endpoint	Speed	Data Freshness
Form autocomplete	`/v2/companies/search/autocomplete`	~50ms	Indexed
Find companies	`/v2/companies/search/`	2-5s	Real-time
Pre-fill forms	`/v2/companies/{id}/prefill`	~200ms	Indexed + fallback
Full company data	`/v2/companies/{id}/report`	2-30s	Real-time
Ownership structure	`/v2/companies/{id}/shareholder-graph`	5-60s	Real-time

Handling Errors

All endpoints return standard HTTP status codes:

Status	Meaning
200	Success
400	Invalid request (check request body)
401	Invalid or missing API key
404	Company not found
408	Request timeout (sync mode only)
429	Rate limit exceeded
500	Server error

For async operations, check the status field:

running — Still processing
completed — Result available in result field
failed — Check error field for details

Why timeouts happen

Kausate fetches data directly from official government registries (Handelsregister, Companies House, etc.). These external systems are inherently unreliable:

Rate limiting — Registries limit requests to prevent abuse
Maintenance windows — Government systems have scheduled and unscheduled downtime
Slow responses — Some queries take 30+ seconds depending on registry load
Temporary outages — Network issues and server errors are common

This is why we recommend asynchronous requests with webhooks (recommended) or polling using the orderId. Our retry logic handles temporary failures automatically, and you'll receive results as soon as they're available.

On this page