Overview
We’re shipping an async order pattern on V2 Enhanced Profile: a fire-and-forgetPOST + poll for production, plus a 202 fallback on GET for cases where upstream fulfilment exceeds the connection-hold window.
POST V2 Enhanced Profile is being introduced for an initial preview rollout covering GB, IE, LU, EE, LV, CN, JP, HK.
For jurisdictions in scope, orders will be placed with POST /v2/companies/{kyckrId}/enhanced — no connection hold — and polled via GET /v2/orders/{orderId} for the profile when ready.
Independently, when upstream fulfilment on GET /v2/companies/{kyckrId}/enhanced exceeds the ~40s connection-hold window, the server will return 202 with an orderId instead of timing out.
What’s changing:
POST /v2/companies/{kyckrId}/enhancedwill be the recommended production pattern for the registries above — returns anorderIdimmediately with no server-side connection hold; pollGET /v2/orders/{orderId}to retrieve the profile when readyGET /v2/companies/{kyckrId}/enhancedwill work for all jurisdictions — server holds up to ~40s and returns200with data if ready, or202withorderIdif not (the202fallback is the change here; today, slow orders time out)405will be removed fromGET /enhancedresponses- Action required: to retrieve data from slow-running orders once this is live, your integration needs to handle the
202response onGETor usePOST + poll.
Background
Today, slow-running orders that exceed the ~40s connection-hold window time out without delivery. For most jurisdictions fulfilment completes well inside the window and time-outs do not occur. The async order pattern will ensure slow orders complete and become retrievable through the polling workflow described below.Flow overview
Recommended pattern — POST + poll
Why POST + poll for production
Holding open HTTP connections server-side costs infrastructure capacity at scale. Every connection held for ~40s waiting for a slow registry is a server resource occupied that could serve other requests. For high-volume clients, this accumulates: a pipeline of 100 concurrent profile requests holds 100 connections open for up to 40s each. POST + poll eliminates that: the server returns anorderId immediately, the connection closes, and the client polls on its own schedule.
How it works
Status values (poll response)
Polling cadence: use exponential backoff (start with a short interval, increase up to a sensible cap). Treat orders still showing a Pending status after your tolerance window as exceeded — 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.
Convenience pattern — GET with 202 fallback
For ad-hoc lookups, manual exploration, or low-volume integrations where connection overhead is not a concern,GET /enhanced provides a synchronous-feel interface:
Location header as the poll URL. Poll GET /v2/orders/{orderId} until data.status is Success.
Comparison
405 removal
405 Method Not Allowed will be removed from GET /enhanced responses. Clients that currently handle 405 on this endpoint should remove that branch — it will no longer be returned. Replace any 405 handling with 202 handling as above.
Integration guidance
For production pipelines: use POST + poll. Handle201 on POST, then poll GET /v2/orders/{orderId}.
For ad-hoc / low-volume: GET is fine. Handle both 200 (immediate data) and 202 (poll for completion).
For mixed-pattern jurisdictions (HK in particular): expect a mix of 200 and 202 responses once live. POST + poll remains the production-grade choice (resource-efficient at scale regardless of jurisdiction); GET-with-202 is fine for ad-hoc use.
Recovering a lost orderId
If your process loses theorderId after receiving a 201 or 202 (for example, a crash before persisting), don’t re-issue the POST — 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 (if supplied) or scanning recent items.
Best practice: persist the
orderId immediately on receipt of 201 or 202, before any further work. Treat it as a transactional checkpoint.Jurisdiction rollout
The initial preview rollout forPOST /v2/companies/{kyckrId}/enhanced covers the following jurisdictions:
This scope reflects the initial preview rollout. If your integration would benefit from the async pattern for additional jurisdictions, contact your account manager — we welcome feedback on prioritisation.
GET 202 fallback is independent of the POST rollout — it will fire for any jurisdiction where upstream fulfilment exceeds ~40s.
What you need to do
This change is in development. Specific dates will land in the release-day announcement; this notice is to let you plan the integration work now. Before go-live: orders that exceed the ~40s window time out. No data delivered, no charge applied. (Current behaviour, unchanged.) After go-live: orders that exceed the ~40s window return202 with an orderId. The order continues processing; data becomes available via the polling workflow above. Charges apply when data is delivered.
To retrieve data from these orders, your integration needs to handle the 202 response — or use POST + poll, recommended for production volumes (see above). Until your handler is in place, slow orders will complete upstream and be billed at delivery — they remain available via GET /v2/orders/{orderId} until your code is updated to retrieve them.
Cadence of communications:
- Today: this preview notice — plan the
202handler (orPOST + poll) now. Luxembourg is the priority jurisdiction: LU async orders currently can time out, and once the change is live, the new patterns are how you retrieve data for slow LU orders. - Go-live (date TBC): change is active in production. This is a non-breaking change — no separate test phase or final notice is planned.