KausateKausate Docs

Sync and async

How to call real-time operations asynchronously or synchronously, and how to get the results

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

ApproachBest ForTrade-offs
Webhooks (recommended)Production systems, high reliabilityRequires a publicly accessible endpoint
PollingSimple integrations, serverless environmentsAdds latency, requires polling logic
SyncTesting, prototyping, one-off requestsMay 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

EndpointAsync PathSync Path
Auto-complete—GET /v2/companies/search/autocomplete
Live SearchPOST /v2/companies/searchPOST /v2/companies/search/sync
Prefill—POST /v2/companies/prefill
List DocumentsPOST /v2/companies/documents/listPOST /v2/companies/documents/list/sync
Document RetrievalPOST /v2/companies/documentsPOST /v2/companies/documents/sync
Company ReportPOST /v2/companies/reportPOST /v2/companies/report/sync
FinancialsPOST /v2/companies/financePOST /v2/companies/finance/sync
UBO ExtractionPOST /v2/companies/uboPOST /v2/companies/ubo/sync
Shareholder GraphPOST /v2/companies/shareholder-graphPOST /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 "Kausate-Version: 2026-08-01" \
  -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",
  "metadata": null,
  "customerId": null,
  "cachedOrder": false,
  "resultUrl": "/v2/companies/report/ord_xyz789"
}

Kausate retries register timeouts and outages in the background.

Order Time Budgets

Set globalTimeout in the POST body to give an order a time budget in whole minutes, from 1 to 10,080. The budget starts when the order is queued. On expiry, acquisition stops and cleanup can finish before the order closes. Polling an expired order returns request.timeout in the code field.

Shareholder graph orders and extensions return the graph collected so far with stopReason: "time_budget_exhausted". You can extend the graph to continue acquisition. Graph orders default to seven days when the field is omitted. Other orders retain their existing defaults, including shorter limits on synchronous endpoints.

Shareholder Graph Spend Limits

Set maxCredits on a shareholder graph order or extension to limit what the order spends acquiring data: the registry fees and document extraction of every company it extracts, added up in credits. The limit does not change the price of the order. 0, the default, sets no limit.

With a limit, the largest shareholders are extracted first. When the next company no longer fits, the order returns the graph collected so far with stopReason: "budget_exhausted". You can extend the graph to continue. The first company is always extracted, so an order never returns an empty graph because of its limit. The limit is checked before each batch of companies starts, so a batch that costs more than the ones before it can take the total over the limit.

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 "Kausate-Version: 2026-08-01" \
  -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.

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 "Kausate-Version: 2026-08-01" \
  -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 "Kausate-Version: 2026-08-01" \
  -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:

SettingValue
Maximum attempts10 by default; 1 when you choose no retries for development
Initial interval1 second
Backoff multiplier2x
Total retry windowAbout 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" \
  -H "Kausate-Version: 2026-08-01"

Polling endpoints:

RequestEndpoint
Document RetrievalGET /v2/companies/documents/{orderId}
List DocumentsGET /v2/companies/documents/list/{orderId}
Company ReportGET /v2/companies/report/{orderId}
Shareholder GraphGET /v2/companies/shareholder-graph/{orderId}
UBO ExtractionGET /v2/companies/ubo/{orderId}
FinancialsGET /v2/companies/finance/{orderId}
Live SearchGET /v2/companies/search/{orderId}

The following polling responses are abbreviated.

Response (while processing):

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

currentActivity is a human-readable label for the current step.

An order can stay running for a long time without anything being wrong — a registry that is closed outside its opening hours, down for maintenance, or still preparing a document. While that is the case, waitingMessage says why in a plain sentence you can show to your users, with the time of the next attempt where it is known. It is null when the order is not waiting:

{
  "orderId": "ord_xyz789",
  "status": "running",
  "currentActivity": "Searching registry",
  "waitingMessage": "The Alberta Corporate Registry is closed outside its opening hours. Your order will continue automatically when it reopens. The next attempt is at about 12:17 UTC on 21 October 2026."
}

Response (completed):

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

Order statuses:

StatusMeaning
runningStill processing — check back later
completedResult available in the result field
failedThe order failed — check error and code
canceledOrder was canceled
terminatedOrder was terminated
timedOutProcessing 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 "Kausate-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -d '{
    "kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
    "customerReference": "kyc-check-456"
  }'

Timeouts:

EndpointTimeout
Prefill30 seconds
All /sync endpoints300 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 "Kausate-Version: 2026-08-01" \
  -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.

API version 2025-04-01

Clients pinned to Kausate-Version: 2025-04-01 call the same operations in an older shape:

  • The company identifier is part of the URL, for example POST /v2/companies/{kausateId}/report, instead of the request body.
  • Synchronous execution is the ?sync=true query parameter on the same URL, not a /sync path.
  • Search and list-documents are synchronous by default; pass ?sync=false to get an order. Shareholder graph is asynchronous only.

Webhooks, polling and daily deduplication work as described above.

Last updated on

On this page