This is an early notice — specific dates for test-environment and go-live will land in follow-up notices.
Overview
We’re shipping an async order pattern on V2 Enhanced Profile: a fire-and-forget POST + 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}/enhanced will be the recommended production pattern for the registries above — returns an orderId immediately with no server-side connection hold; poll GET /v2/orders/{orderId} to retrieve the profile when readyGET /v2/companies/{kyckrId}/enhanced will work for all jurisdictions — server holds up to ~40s and returns 200 with data if ready, or 202 with orderId if not (the 202 fallback is the change here; today, slow orders time out)405 will be removed from GET /enhanced responses- Action required: to retrieve data from slow-running orders once this is live, your integration needs to handle the
202 response on GET or use POST + 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 an orderId immediately, the connection closes, and the client polls on its own schedule.
How it works
POST /v2/companies/{kyckrId}/enhanced
→ 201 Created
Location: /v2/orders/12345
{
"orderId": "12345",
"status": "Pending"
}
GET /v2/orders/12345
→ 200 OK (when status = Success)
| Step | Endpoint | Notes |
|---|
| 1. Place order | POST /v2/companies/{kyckrId}/enhanced | Returns orderId immediately; 201 Created |
| 2. Poll | GET /v2/orders/{orderId} | Poll until data.status = Success |
| 3. Retrieve | Profile data in order result | Same payload as a 200 from GET |
Status values (poll response)
data.status | Meaning |
|---|
Pending | Order queued; profile not yet ready |
Success | Profile ready — retrieve from order result |
Failed | Fulfilment failed — retry or contact support |
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:
GET /v2/companies/{kyckrId}/enhanced
→ 200: full EnhancedProfile payload (fast path)
→ 202: orderId + Location header (profile not ready within ~40s)
HTTP/1.1 202 Accepted
Location: /v2/orders/12345
Content-Type: application/json
{
"orderId": "...",
"correlationId": "...",
"timeStamp": "...",
"data": {
"orderId": "12345",
"status": "Pending",
"estimatedCompletion": "2026-06-09T10:30:00Z"
}
}
Location header as the poll URL. Poll GET /v2/orders/{orderId} until data.status is Success.
Comparison
| POST (recommended for production) | GET (convenience) |
|---|
| Connection hold | None — returns immediately | Up to ~40s |
| Response when fast | 201 with orderId | 200 with profile data |
| Response when slow | 201 with orderId | 202 with orderId |
| Best for | High-volume pipelines; resource-conscious integrations | Ad-hoc lookups; low-volume; sync-feel preference |
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. Handle 201 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 the orderId 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 for POST /v2/companies/{kyckrId}/enhanced covers the following jurisdictions:
| ISO | Jurisdiction | Slow-fulfilment behaviour today |
|---|
GB, IE, EE, LV, CN, JP | UK, Ireland, Estonia, Latvia, China, Japan | Fulfilment typically completes within the ~40s connection-hold window |
LU | Luxembourg | Slow orders currently time out — addressed by POST + poll or GET 202 once the async pattern is live |
HK | Hong Kong | Slow orders today may time out — addressed by POST + poll or GET 202 once the async pattern is live |
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 return 202 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
202 handler (or POST + 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.
Additional resources
