Async & Sync Processing

Kausate fetches company data directly from official government registries in real time. These registries are inherently unreliable — timeouts, rate limits, and maintenance windows are common. To handle this gracefully, most data retrieval endpoints default to asynchronous processing.

Choosing the Right Approach

General recommendation: Use async mode with webhooks for production. Fall back to polling if you can't expose a webhook endpoint. Use sync mode only during development and testing.

Endpoint Defaults

Async Mode

When you make a request to an async endpoint, the API returns immediately with an 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"}'

Response:

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

Kausate handles registry timeouts and temporary outages in the background — no action needed from you.

Getting Results: Webhooks (Recommended)

Webhooks are the most reliable way to receive results. Once configured, Kausate sends the completed result to your endpoint automatically.

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": "Order Results",
    "url": "https://your-server.com/webhooks/kausate"
  }'

You can also include custom headers for authentication:

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",
    "headers": {
      "Authorization": "Bearer your_webhook_secret"
    }
  }'

Webhook payload:

When an order completes, Kausate sends a POST request to your webhook URL with the full ExecutionResponse — the same payload you'd get from polling the matching typed run endpoint.

Webhook retry policy:

If your endpoint is temporarily unreachable, Kausate keeps retrying with exponential backoff.

Getting Results: Polling

If you prefer not to set up a webhook, poll the typed run endpoint for the workflow family you started:

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

Common polling endpoints:

Response (while processing):

{
  "orderId": "ord_xyz789",
  "status": "running",
  "currentActivity": "Fetching company data from Handelsregister"
}

The currentActivity field shows a human-readable label describing the current processing step.

Response (completed):

{
  "orderId": "ord_xyz789",
  "status": "completed",
  "result": {
    "basicInformation": {
      "legalName": "Bundesanzeiger Verlag GmbH",
      "..."
    }
  }
}

Order statuses:

Sync Mode

For endpoints that support it, append ?sync=true to the request URL. The API will wait for the result and return it inline:

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

The response contains the full result directly — no need for polling or webhooks.

Timeouts:

If the request exceeds the timeout, you'll receive an HTTP 408 response.

Daily Deduplication

When you make the same request (same endpoint, same company, same parameters) on the same day, Kausate reuses the existing order instead of starting a new one. You'll receive the same orderId and result.

This means:

• Duplicate requests don't consume additional credits
• You can safely retry requests without worrying about double-billing
• Results are cached for the remainder of the calendar day

To force a fresh request that bypasses the cache, include bypassCache in the request body:

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",
    "bypassCache": true
  }'