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

# How domains work

> Statuses, inventory vs connected, usable_for, imports, and forwarding.

A domain is a sending domain in your partner account. The same `dom_01HZX` ID
stays with it whether or not it is on an order.

## Statuses

| Value             | Meaning                                          |
| ----------------- | ------------------------------------------------ |
| `available`       | In inventory. Not on an order yet.               |
| `in_progress`     | Being set up.                                    |
| `active`          | Live and warming or healthy.                     |
| `failed`          | Broken in a way Peeker cannot fix automatically. |
| `action_required` | Needs your help (for example, nameservers).      |

## Inventory vs connected

List with `GET /domains` and filter by `category`:

| Category    | Meaning                | Extra fields                                                          |
| ----------- | ---------------------- | --------------------------------------------------------------------- |
| `inventory` | Yours, not on an order | No `provider`                                                         |
| `connected` | On an active order     | `provider`, `customer_id`, `order_id`, `usable_for`, `forwarding_url` |

<Note>
  Connected `usable_for` reflects the ESP already on the domain. Availability checks use the tenant
  matrix below. They are not the same source.
</Note>

## `usable_for` (availability)

When you call `POST /domains/availability`:

| Who is on the domain        | `usable_for`                                       |
| --------------------------- | -------------------------------------------------- |
| Nobody, or only Google      | `["google", "microsoft"]`                          |
| Microsoft (or both)         | `["google"]`                                       |
| Premium / invalid / errored | Not orderable. `available: false` with a `reason`. |

If the tenant check cannot answer, `usable_for` is omitted rather than guessed.

`POST /domains/generate` uses the same tenant matrix, then keeps only names
usable for both Google and Microsoft. It groups those names by TLD and does
not return `usable_for`. `GET /domains/tlds` lists the active TLDs you may
pass into generate. Omit `tlds` to generate `.com` only.

| Cache                  | Window                          |
| ---------------------- | ------------------------------- |
| Registrar availability | Rechecked after about 5 minutes |
| Tenant / `usable_for`  | Can be reused for up to 35 days |

## Imports and forwarding

| Job          | Endpoint                              | Behavior                                                                                       |
| ------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Sync import  | `POST /domains/import` (max 25)       | Waits for the result (`200`). Status is terminal: `completed`, `failed`, or `action_required`. |
| Async import | `POST /domains/import/jobs` (max 500) | Returns `202` with `status: "in_progress"`. Poll or use `domain_import.*` webhooks.            |
| Forwarding   | `POST /domains/forwarding` (max 25)   | Always async (`fwj_…`). Poll or use `domain.forwarding_*` webhooks.                            |

Import jobs use prefix `imp_…`. Successful imports often include
`nameserver_groups` the customer may need at their registrar.

`action_required` on an import means a partial result: some domains imported
and others failed. It is not “still waiting on nameservers.”

Already-correct forwarding domains still succeed and appear in `completed`.

<CardGroup cols={2}>
  <Card title="Importing domains" href="/guides/importing-domains">
    Bring in customer-owned domains, then order.
  </Card>

  <Card title="Forwarding" href="/guides/forwarding">
    Point live domains at a marketing URL.
  </Card>
</CardGroup>