Overview
We’re introducing an async order pattern on V2 Enhanced Profile, in two forms:POST+ poll, the recommended pattern for production integrations: place an order, poll it, retrieve the profile.- A
202fallback onGET: a request the registry can’t fulfil in time returns a pollable order instead of timing out.
202 response on GET, or use POST + poll.
Jurisdiction rollout
POST + poll
POST /v2/companies/{kyckrId}/enhanced is available for every jurisdiction where an Enhanced Profile is available. No jurisdiction is excluded.
Some jurisdictions are POST-only. Hong Kong Enhanced Profile is the one example today: registry fulfilment there runs too long for a held connection, so it has never been available via GET and is available only via POST. Future jurisdictions with slow registries, including some upcoming Canadian registries, will follow the same POST-only route.
GET with 202 fallback
TheGET 202 fallback is enabled per jurisdiction, independently of the POST rollout: it applies only where the jurisdiction is served by the GET profile endpoint and fulfilment has shown a tendency to run long enough to time out.
Luxembourg is the only such jurisdiction today. A GET request for LU has two possible success responses: 200 with the profile, or 202 with an order ID to retrieve the profile when available.
Background: the GET route
GET /v2/companies/{kyckrId}/enhanced holds the connection open while the registry fulfils the order. Most fulfilment completes quickly; a slow order can hold the connection far longer before eventually timing out, and a timed-out request loses its result. A GET request typically has a person waiting on it, so rather than hold toward that timeout, the fallback draws the line at ~40 seconds: if the profile hasn’t arrived, the request returns 202 with an order instead, and the profile is retrieved from the order once fulfilment completes.
Flow overview
POST + poll
GET with 202 fallback
Recommended pattern: POST + poll
Why POST + poll for production
Holding open HTTP connections server-side costs infrastructure capacity, and a connection held waiting on a slow registry is a resource that could serve other requests. POST + poll avoids the hold entirely: the server returns anorderId immediately, the connection closes, and the client polls on its own schedule.
How it works
data.status reaches Success, the order result carries the profile, identical to a 200 from GET /enhanced.
Status values (poll response)
Polling cadence: use exponential backoff: start with a short interval and increase it up to a sensible cap. Delivery timeframes vary considerably by jurisdiction: review the expected timeframe for each jurisdiction you order from, and size your backoff intervals and upper limits to match. Treat orders still showing a Pending status after your tolerance window as having exceeded it: investigate or contact support. Don’t poll on a tight loop; the order-status endpoint is shared across products and aggressive polling will degrade your other API calls.
Recovering a lost orderId
If your process loses theorderId after receiving a 202, don’t re-issue the request: that creates a new order placement and is billed separately. Instead, recover the orderId by listing recent orders via GET /v2/orders and filtering on your customerReference, or by scanning recent items.