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

# Async jobs and webhooks

> Which Partner API calls return immediately, what to poll, and when to use webhooks.

Many Partner writes accept work and finish later. Use the same pattern
everywhere.

## Pattern

<Steps>
  <Step title="Call the write endpoint">
    Capture the public ID (`ord_…`, `imp_…`, `fwj_…`, `pcl_…`, `prl_…`, `swp_…`, `brj_…`).
  </Step>

  <Step title="Listen or poll">
    Return `2xx` from your webhook handler quickly, or poll the GET resource.
  </Step>

  <Step title="Branch on status">
    Use `status` / `data.status`. Do not depend on event arrival order.
  </Step>
</Steps>

Delivery is at least once. Dedupe on `Peeker-Event-Id` for at least 24 hours.

See [Webhooks](/webhooks).

## What is async

| Work                | Start                                   | Poll                               | Webhooks              |
| ------------------- | --------------------------------------- | ---------------------------------- | --------------------- |
| Orders              | `POST /orders`                          | `GET /orders/{id}`                 | `order.*`             |
| Pending actions     | (status only)                           | `GET /orders/pending`              | (none)                |
| Async domain import | `POST /domains/import/jobs`             | `GET /domains/import/jobs/{id}`    | `domain_import.*`     |
| Forwarding          | `POST /domains/forwarding`              | `GET /domains/forwarding/{id}`     | `domain.forwarding_*` |
| Pool attach         | `POST /pool/attach`                     | `GET /pool/reservations/{id}`      | `pool.claim.*`        |
| Pool release        | `POST /pool/release`                    | `GET /pool/releases/{id}`          | `pool.release.*`      |
| Pool replacement    | (automatic)                             | reservation / events               | `pool.replacement.*`  |
| Domain / name swaps | `POST /swaps`, `POST /swaps/user_names` | `GET /swaps/{id}`                  | `swap.*`              |
| Burned replace      | `POST /domains/burned/replace`          | `GET /domains/burned/replace/{id}` | (poll job / results)  |

## What is synchronous

| Work                                            | Notes                                   |
| ----------------------------------------------- | --------------------------------------- |
| `POST /domains/import` (max 25)                 | Waits and returns a terminal import job |
| `POST /domains/availability`                    | Returns availability + `usable_for`     |
| `POST /domains/generate`                        | Both-provider names grouped by TLD      |
| Most list/get/create for workspaces and bundles | Immediate resource response             |

<Tip>
  Before going live, verify one success path, one error path, and webhook signature handling.
</Tip>