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

> The V2 Enhanced Profile async order pattern: POST + poll for production, plus a 202 fallback on GET.

## 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 **`202` fallback on `GET`**: a request the registry can't fulfil in time returns a pollable order instead of timing out.

**Action required:** once this is live, your integration needs to handle the `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

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

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

    C->>A: POST /v2/companies/{kyckrId}/enhanced
    A-->>C: 202 Accepted, orderId in response body
    loop Poll with backoff
        C->>A: GET /v2/orders/{orderId}
        A-->>C: 200 OK, status: Pending or Success
    end
```

### GET with 202 fallback

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

    C->>A: GET /v2/companies/{kyckrId}/enhanced
    alt Fast path
        A-->>C: 200 OK, profile data
    else Slow path
        A-->>C: 202 Accepted, orderId in response body
        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, 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 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
→ 202 Accepted
```

```json theme={null}
{
  "correlationId": "...",
  "timeStamp": "...",
  "data": {
    "status": "Pending",
    "orderId": 12345,
    "cost": {
      "type": "credit",
      "value": 1
    }
  }
}
```

Then poll until complete:

```http theme={null}
GET /v2/orders/12345
→ 200 OK (when status = Success)
```

When `data.status` reaches `Success`, the order result carries the profile, identical to a 200 from `GET /enhanced`.

### 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 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 the `orderId` 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.

## Additional resources

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