> ## 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 — GET with 202 Fallback

> Preview of the V1 Enhanced Profile async order pattern: GET will return 202 with a numeric orderId when upstream fulfilment exceeds the connection-hold window, instead of timing out. Initial preview rollout covers GB, IE, LU, EE, LV, CN, JP, HK.

This is an early notice — specific dates for test-environment and go-live will land in follow-up notices.

## Overview

We're shipping a `202` fallback on `GET /core/company/profile/{countryISO}/{companyCode}` so that slow-running orders no longer time out without delivery. When upstream fulfilment exceeds the \~40s connection-hold window, the endpoint will return `202` with a numeric `orderId` you can poll on the V1 order-status endpoint.

The 202 fallback will fire only when upstream fulfilment is slow. For most jurisdictions this does not happen — orders complete inside the connection-hold window and return `200` as usual. The `202` path is the change here.

### Where the 202 will fire

The `202` fallback is part of the new registry integrations that also bring [V2 POST Enhanced Profile](/company-v2/developer-news/2026-06-async-order-pattern):

* Slow-fulfilment cases are primarily observed today for Luxembourg orders, which currently time out without delivery. Once the new integration is live for LU, those orders will return `202` instead.
* **Hong Kong** also has slow orders today that can time out. Once the async pattern is live for HK, those orders will return `202` instead.
* For all other jurisdictions, you should not see `202` on V1 GET Enhanced Profile under normal conditions.

### Key points

* **`GET /core/company/profile/{countryISO}/{companyCode}` will return 202** when the upstream provider does not fulfil the profile within \~40s
* **`orderId` in the 202 response is numeric** — it corresponds to `productOrderIdField` in the order-status list
* **Polling uses the V1 order-status endpoint** — `GET /core/filing/order-status/{orderedWithin}`
* **Single endpoint** — `GET /core/company/profile/{countryISO}/{companyCode}`; the new `202` fallback will apply to this endpoint
* **Action required:** once your registry is on the new integration, slow orders that previously timed out will return `202`. To retrieve their data, your integration needs to handle the `202` response.

## 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 upstream and become retrievable through the polling workflow described below.

## Flow overview

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

    C->>A: GET /core/company/profile/{countryISO}/{companyCode}
    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 /core/filing/order-status/1
            A-->>C: array of ProductListItem
            C->>C: Find item where productOrderIdField == orderId
        end
        C->>U: GET urlField (when statusField = 2, 21, or 3)
        U-->>C: Enhanced profile document
    end
```

## New behaviour — GET with 202 fallback

### How it works

1. Call `GET /core/company/profile/{countryISO}/{companyCode}` as usual
2. **Fast path (\< \~40s):** server returns `200 OK` with the full enhanced profile — no change to existing behaviour
3. **Slow path (> \~40s):** server returns `202 Accepted` with a numeric `orderId` and a `Location` header

When you receive 202:

```http theme={null}
HTTP/1.1 202 Accepted
Location: /core/filing/order-status/1
Content-Type: application/json
```

```json theme={null}
{
  "orderId": 10818754,
  "status": "Pending",
  "estimatedCompletion": "2026-06-09T10:30:00Z"
}
```

Use the `Location` header as the poll URL (the canonical pattern). The `/core/filing/order-status/{orderedWithin}` form documented below is the explicit form used when you're not following the Location header directly.

### Polling for completion

<Note>The `orderId` returned in the `202` response body is the same numeric value as `productOrderIdField` in the order-status list response. They're the same identifier; the field name differs across the two endpoints.</Note>

`orderedWithin` is the number of days to look back for orders. Integer, range 0–30 (where 0 means today). Choose a window comfortably wider than your expected fulfilment time — `orderedWithin=1` (last 24 hours) is sufficient for any order that completes within minutes.

Poll `GET /core/filing/order-status/{orderedWithin}` and scan the returned array for the item whose `productOrderIdField` matches the numeric `orderId` from the 202 response:

```text theme={null}
GET /core/filing/order-status/1
→ array of ProductListItem

Find item where productOrderIdField == 10818754
Check statusField — when it indicates completion:
  retrieve profile from urlField or structuredDataUrlField
```

### Status values (V1 order-status response)

| `statusField`  | Meaning                                                      |
| -------------- | ------------------------------------------------------------ |
| `1`            | Pending — order in progress                                  |
| `2`, `21`, `3` | Ready — retrieve from `urlField` or `structuredDataUrlField` |
| `5`            | Failed                                                       |
| `9`            | Cancelled                                                    |

See the [Order Documents guide](/documentation/features/retrieve-a-document-v1) for the canonical reference on V1 order status values.

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

### Result retrieval

When the order completes, the result is available via two URL fields:

* `urlField` — the document/profile artifact URL.
* `structuredDataUrlField` — a structured-data version of the result, where available.

Whether `structuredDataUrlField` is populated depends on jurisdiction and product. Check both fields and fall back from one to the other if your integration prefers a specific format.

### Recovering a lost orderId

If your process loses the `orderId` after receiving 202 (for example, a crash before persisting), don't re-call `GET /core/company/profile/...` — that creates a new order placement and is billed separately. Instead, recover the `orderId` from the order-status list endpoint by filtering on your `orderRef` (if you supplied one) or scanning recent items.

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

## Integration guidance

Handle `202` alongside `200`:

```text theme={null}
GET /core/company/profile/{countryISO}/{companyCode}
  → 200: use response data directly
  → 202: store orderId (numeric), poll GET /core/filing/order-status/1
         find item where productOrderIdField == orderId
         when statusField is 2, 21, or 3 — retrieve from urlField
```

**For LU and HK (once each migrates):** expect a mix of `200` and `202` responses on V1 GET Enhanced Profile. Build and test the `202` branch from the start so you don't lose data on the orders that exceed the \~40s window.

<Info>**Want fire-and-forget?** V1 will support the slow-order case fully via `GET` + `202` handling. If you'd prefer a fire-and-forget alternative — `POST` returns an `orderId` immediately with no server-side connection hold — V2 offers `POST + poll` as the recommended production pattern for the new-integration registries across the rollout (GB, IE, LU, EE, LV, CN, JP, HK). See the [V2 release note](/company-v2/developer-news/2026-06-async-order-pattern).</Info>

## Jurisdiction rollout

The initial preview rollout for the V1 `202` fallback covers the following jurisdictions:

| ISO                     | Jurisdiction                 | Slow-fulfilment behaviour today                                                                          |
| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `LU`                    | Luxembourg                   | Slow orders currently time out — will return `202` once the async pattern is live                        |
| `HK`                    | Hong Kong                    | Slow orders today may time out — will return `202` once the async pattern is live                        |
| `CN`, `JP`              | China, Japan                 | Slow-fulfilment cases are uncommon today; the `202` fallback will be in place once live                  |
| `GB`, `IE`, `EE`, `LV`  | UK, Ireland, Estonia, Latvia | Fulfilment typically completes within the connection-hold window; `202` unlikely under normal conditions |
| All other jurisdictions | —                            | `202` not expected; not in the preview rollout                                                           |

<Note>This scope reflects the initial preview rollout. If your integration would benefit from the `202` fallback for additional jurisdictions, contact your account manager — we welcome feedback on prioritisation.</Note>

## 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.** On V1, the 202 handler is how slow-running order data reaches your integration. Until your handler is in place, slow orders will complete upstream and be billed at delivery — they remain available via the polling endpoint until your code is updated to retrieve them.

**Cadence of communications:**

* Today: this preview notice — plan the `202` handler now. **Luxembourg is the priority jurisdiction:** LU async orders currently can time out, and once the change is live, the `202` handler is 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 V1 API Reference](/company-v1/api-reference/overview)
* [Company V1 Changelog](/company-v1/api-reference/changelog)
* [Order Documents guide](/documentation/features/retrieve-a-document-v1)
* [Hong Kong country guide](/country-guides/hong-kong)
* [Enhanced Profile guide](/documentation/features/perform-a-kyb-check-v1)