> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyckr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Order Pattern for Enhanced Profile — POST + Poll Recommended

> Preview of the V2 Enhanced Profile async order pattern: POST + poll for production, plus a 202 fallback on GET when upstream fulfilment exceeds the connection-hold window. Rolling out registry-by-registry across GB, IE, LU, EE, LV, CN, JP, HK. 405 removed from GET enhanced.

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 ready
* `GET /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

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant A as Kyckr API

    Note over C,A: POST + poll (recommended for production)
    C->>A: POST /v2/companies/{kyckrId}/enhanced
    A-->>C: 201 Created — orderId + Location header
    loop Poll with backoff
        C->>A: GET /v2/orders/{orderId}
        A-->>C: 200 OK — status: Pending or Success
    end

    Note over C,A: GET + 202 fallback (convenience)
    C->>A: GET /v2/companies/{kyckrId}/enhanced
    alt Fast path (< ~40s)
        A-->>C: 200 OK — profile data
    else Slow path (> ~40s)
        A-->>C: 202 Accepted — orderId + Location header
        loop Poll with backoff
            C->>A: GET /v2/orders/{orderId}
            A-->>C: 200 OK — status: Pending or Success
        end
    end
```

## 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

```http theme={null}
POST /v2/companies/{kyckrId}/enhanced
→ 201 Created
Location: /v2/orders/12345
```

```json theme={null}
{
  "orderId": "12345",
  "status": "Pending"
}
```

Then poll until complete:

```http theme={null}
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 |

**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:

```http theme={null}
GET /v2/companies/{kyckrId}/enhanced
→ 200: full EnhancedProfile payload (fast path)
→ 202: orderId + Location header (profile not ready within ~40s)
```

When you receive 202:

```http theme={null}
HTTP/1.1 202 Accepted
Location: /v2/orders/12345
Content-Type: application/json
```

```json theme={null}
{
  "orderId": "...",
  "correlationId": "...",
  "timeStamp": "...",
  "data": {
    "orderId": "12345",
    "status": "Pending",
    "estimatedCompletion": "2026-06-09T10:30:00Z"
  }
}
```

Use the `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.

<Note>**Best practice:** persist the `orderId` immediately on receipt of `201` or `202`, before any further work. Treat it as a transactional checkpoint.</Note>

## 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 |

<Note>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.</Note>

The `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

* [Company V2 API Reference](/company-v2/api-reference/overview)
* [Company V2 Changelog](/company-v2/api-reference/changelog)
* [Hong Kong country guide](/country-guides/hong-kong)
* [Enhanced Profile guide](/documentation/features/perform-a-kyb-check-v2)