Skip to main content

Sync vs Async Flows

Zenoo supports two execution models. Choose based on whether user interaction is required and how your system handles latency.
Quick rule: server-to-server checks use sync. User-facing journeys use async.

Synchronous (Model 1)

The API blocks until all checks complete or the timeout is reached. Results are returned in the response body.

How to use

Add the X-SYNC-TIMEOUT header to any /api endpoint. The value is in milliseconds.
The API holds the connection open for up to X-SYNC-TIMEOUT milliseconds, then returns whatever results are available.

When to use

  • Server-to-server checks: AML screening, company registry verification
  • Automated pipelines: batch processing, background jobs, cron tasks
  • Simple flows: single-provider checks that complete quickly
  • Development and testing: fastest way to see results

Timeout behavior

If the response contains a tokens field, some checks are still processing. Use the pull token to retrieve the remaining results.
Setting timeouts below 10 seconds forces unnecessary polling. Setting them above 90 seconds ties up HTTP connections without benefit. Start with the recommended values and adjust based on your p95 latency.

Comparison table

Processing timeline

Typical durations for each processing stage: Person Verification elapsed time is dominated by user behavior: finding documents, taking photos, retrying failed captures. Once the user submits, server-side processing completes in 30 to 60 seconds.

Mixing models

Most production integrations use both models. A typical pattern:
  1. Company Verification (sync). Submit company data, get results in the response.
  2. Person Verification (async). Initiate journeys for directors and UBOs, redirect them to verification URLs.
  3. Screening (sync). Re-screen existing customers for ongoing monitoring.
integration.js

Polling example (Node.js)

A complete polling implementation with exponential backoff:
poll-results.js

Next steps