Async & Sync Processing
How Kausate handles async and sync data retrieval from government registries
Kausate reads company data from official registers in real time. Registers time out, limit request volume and go down for maintenance, so most data endpoints are asynchronous by default.
Choosing the Right Approach
| Approach | Best For | Trade-offs |
|---|---|---|
| Webhooks (recommended) | Production systems, high reliability | Requires a publicly accessible endpoint |
| Polling | Simple integrations, serverless environments | Adds latency, requires polling logic |
| Sync | Testing, prototyping, one-off requests | May timeout on registry delays |
Use async with webhooks in production, polling if you cannot expose a webhook endpoint, and sync only for development and testing.
Endpoint Defaults
| Endpoint | Async Path | Sync Path |
|---|---|---|
| Auto-complete | — | GET /v2/companies/search/autocomplete |
| Live Search | POST /v2/companies/search | POST /v2/companies/search/sync |
| Prefill | — | POST /v2/companies/prefill |
| List Documents | POST /v2/companies/documents/list | POST /v2/companies/documents/list/sync |
| Document Retrieval | POST /v2/companies/documents | POST /v2/companies/documents/sync |
| Company Report | POST /v2/companies/report | POST /v2/companies/report/sync |
| Financials | POST /v2/companies/finance | POST /v2/companies/finance/sync |
| UBO Extraction | POST /v2/companies/ubo | POST /v2/companies/ubo/sync |
| Shareholder Graph | POST /v2/companies/shareholder-graph | POST /v2/companies/shareholder-graph/sync |
Async Mode
An async endpoint returns an orderId immediately:
curl -X POST https://api.kausate.com/v2/companies/report \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
"customerReference": "kyc-check-456"
}'Response:
{
"orderId": "ord_xyz789",
"kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
"customerReference": "kyc-check-456",
"cachedOrder": false,
"resultUrl": "/v2/companies/report/ord_xyz789"
}Kausate retries register timeouts and outages in the background.
Customer Metadata
Async requests accept an optional JSON metadata object. It is echoed back on the order, in both polling responses and webhook payloads:
curl -X POST https://api.kausate.com/v2/companies/report \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
"customerReference": "kyc-check-456",
"metadata": {
"caseId": "CASE-12345",
"process": "business-onboarding",
"labels": ["priority"]
}
}'{
"orderId": "ord_xyz789",
"customerReference": "kyc-check-456",
"metadata": {
"caseId": "CASE-12345",
"process": "business-onboarding",
"labels": ["priority"]
},
"status": "completed",
"result": {
"type": "companyReport"
}
}metadata is not indexed and cannot be used to search or filter orders. Use customerReference for correlation.
Metadata is stored and logged as provided. Do not include credentials. Public-register values and customer metadata may be retained in logs, error reports and diagnostic records. Serialized JSON metadata is capped at 4 KB per request.
Getting Results: Webhooks (Recommended)
Once a webhook is registered, Kausate sends every completed result to it.
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",
"customHeaders": {
"Authorization": "Bearer your_webhook_secret"
}
}'The create response includes a per-endpoint signingSecret. See
Webhooks for the signed headers, signature
verification and the outbound IP addresses to allowlist.
Webhook payload:
When an order completes, Kausate POSTs the order to your webhook URL. The payload is the same as the polling response.
Webhook retry policy:
| Setting | Value |
|---|---|
| Maximum attempts | 10 by default; 1 when you choose no retries for development |
| Initial interval | 1 second |
| Backoff multiplier | 2x |
| Total retry window | About 9 minutes with the default 10 attempts |
If your endpoint is temporarily unreachable, Kausate retries with exponential backoff unless that webhook is set to one attempt. The one-attempt option is intended for development endpoints that may be unavailable. Set the delivery attempt limit when creating or editing a webhook in the dashboard.
Getting Results: Polling
Without a webhook, poll the order endpoint that matches the request:
curl https://api.kausate.com/v2/companies/report/ord_xyz789 \
-H "X-API-Key: your_api_key"Polling endpoints:
| Request | Endpoint |
|---|---|
| Document Retrieval | GET /v2/companies/documents/{orderId} |
| List Documents | GET /v2/companies/documents/list/{orderId} |
| Company Report | GET /v2/companies/report/{orderId} |
| Shareholder Graph | GET /v2/companies/shareholder-graph/{orderId} |
| UBO Extraction | GET /v2/companies/ubo/{orderId} |
| Financials | GET /v2/companies/finance/{orderId} |
| Live Search | GET /v2/companies/search/{orderId} |
Response (while processing):
{
"orderId": "ord_xyz789",
"status": "running",
"currentActivity": "Fetching company data"
}currentActivity is a human-readable label for the current step.
Response (completed):
{
"orderId": "ord_xyz789",
"status": "completed",
"result": {
"type": "companyReport",
"companyReport": {
"basicInformation": {
"legalName": "Bundesanzeiger Verlag GmbH"
}
}
}
}Order statuses:
| Status | Meaning |
|---|---|
running | Still processing — check back later |
completed | Result available in the result field |
failed | The order failed — check error and code |
canceled | Order was canceled |
terminated | Order was terminated |
timedOut | Processing exceeded the maximum time window |
For shareholder graph orders, you can pass ?includeIntermediateResult=true
to GET /v2/companies/shareholder-graph/{orderId} to get partial results
while the graph is still being expanded. Note that intermediate results
consume credits.
Sync Mode
The /sync sibling of an endpoint waits for the result and returns it inline:
curl -X POST "https://api.kausate.com/v2/companies/report/sync" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
"customerReference": "kyc-check-456"
}'Timeouts:
| Endpoint | Timeout |
|---|---|
| Prefill | 30 seconds |
All /sync endpoints | 300 seconds (5 min) |
If the request exceeds the timeout, you'll receive an HTTP 408 response.
Sync mode is not recommended for production use. A sync request returns HTTP 408 when the register is slow, even if an async order for the same data would have completed.
Daily Deduplication
The same report, ownership, financials or document request (same endpoint, company and parameters) on the same UTC day reuses the existing order: you get the same orderId and result, and it is not charged again. Search and list-documents orders are never deduplicated. A failed order is not reused; repeating it runs again.
customerReference and metadata are not part of the comparison: two requests that differ only in customerReference reuse the same order.
To force a fresh order, set bypassCache in the request body:
curl -X POST https://api.kausate.com/v2/companies/report \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
"customerReference": "kyc-check-456",
"bypassCache": true
}'The day boundary is midnight UTC: a request at 23:59 UTC and another at 00:01 UTC are separate orders.
Last updated on