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

# Buy domains without inboxes

> Register domains without ordering inboxes. Use this to build up your own
domain supply, then order inboxes on those domains later with
`POST /orders`.

The purchase is a normal order with no mailbox provider. It appears in
`GET /orders`, sends the `order.in_progress` and `order.completed`
webhooks (each webhook domain has `provider: null`), and completes once
every domain is registered. Each domain is charged its registration
price from your wallet now, and renews yearly from your wallet unless
you set `auto_renew: false`.

Each domain must be available and not premium, so check names with
`POST /domains/availability` first. One purchase can mix TLDs. Every
domain is bought or none is: an unavailable name or a name already in
an active order rejects the whole request without charging.

`workspace_id` is optional. Send it to assign the domains to that
workspace (and its customer); omit it to keep them in your organization
unassigned. A later `POST /orders` for the same workspace or customer
can use these domains.

Requires a live key with `full` permissions and an `Idempotency-Key`.
Repeating a request with the same key and body returns the same order
without charging again. Sandbox keys return `403 forbidden`.




## OpenAPI

````yaml /openapi.yaml post /domains/purchase
openapi: 3.1.0
info:
  title: Peeker Partner API
  version: 1.0.0
  description: >
    White-label Peeker's email infrastructure: Google Workspace and Microsoft

    365 inboxes, deliverability monitoring, and self-healing domain swaps,

    from your own app. Create a provider workspace target, order licenses with
    imported or

    Peeker-managed domains, and Peeker's backend handles provisioning,

    DNS, forwarding, and lifecycle webhooks.


    Create a provider workspace target with `POST /workspaces`, then send its

    `wrk_...` ID to `POST /orders`. For Smartlead, create one main workspace,

    then add `client_id` to an order only when it should go to a client

    workspace. Omit it to order into the main workspace.


    ## Read first


    - **[Authentication](/authentication)**: bearer keys, live vs sandbox,
    request IDs.

    - **[Rate limits](/rate-limits)**: 600/min per environment, shared by all
    your keys, 429 backoff.

    - **[Webhooks](/webhooks)**: signed events and delivery rules.

    - **[Async jobs](/concepts/async-jobs)**: what to poll vs subscribe to.

    - **[Best practices](/best-practices)**: errors, paging, idempotency.


    ## Concepts


    - **[Orders](/concepts/orders)**: statuses, sizing, pending actions, cancel.

    - **[Domains](/concepts/domains)**: inventory, `usable_for`, import,
    forwarding.

    - **[Bundles](/concepts/bundles)**: saved templates and capacity.

    - **[Swaps](/concepts/swaps)**: standard vs premium, renames.


    ## Workflow guides


    - **[Provider ordering](/guides/provider-ordering)** — create a provider
    workspace target and order through it.

    - **[Buying domains & ordering](/guides/buying-domains)** — the default
    flow: bundle, availability, order, webhooks.

    - **[Importing domains](/guides/importing-domains)** — bring in existing
    customer domains.

    - **[Forwarding](/guides/forwarding)** — point a domain at a marketing site.

    - **[How to implement domain swaps](/guides/domain-swaps)** — standard vs
    premium swaps.

    - **[Renaming inbox senders](/guides/user-name-swaps)** — change mailbox
    personas on a warm domain.


    ## Public ID prefixes


    | Prefix | Resource |

    | --- | --- |

    | `cus_` | Customer tracking record |

    | `wrk_` | Provider workspace |

    | `bun_` | Bundle |

    | `ord_` | Order |

    | `dom_` | Domain |

    | `pcl_` | Pool reservation |

    | `prp_` | Pool replacement |

    | `prl_` | Pool release |

    | `imp_` | Domain import job |

    | `fwj_` | Domain forwarding job |

    | `brj_` | Burned-domain replacement job |

    | `swp_` | Domain swap |

    | `act_` | Pending action |

    | `evt_` | Webhook event |
servers:
  - url: https://api.peeker.ai/partner/v1
    description: >-
      Same base URL for live and sandbox. The key prefix (`pk_live_…` /
      `pk_test_…`) picks the environment.
security:
  - BearerAuth: []
tags:
  - name: Account
    x-group: Account
    description: >
      Confirm an API key with `GET /me`. Returns environment (live or sandbox),

      permission preset, and the partner profile. See
      [Authentication](/authentication).
  - name: Provider workspaces
    x-group: Provider workspaces
    description: |
      A provider workspace is one reusable provider connection. Create it once,
      keep the returned `wrk_...` ID, and use it in orders and pool attach.
      Optional customer tracking stays on the target. Provider credentials stay
      internal and are never echoed.

      EmailBison requires a workspace API-user key. Super-admin keys are
      rejected. Instantly and Smartlead connections require `api_key`.
      Smartlead workspace creation takes a main API key and a label. Do not send
      `client_id` or customer data. Its login email and password are optional,
      but must be sent together. Google orders do not need the pair, and orders
      never accept it. Smartlead Microsoft orders and pool attach still use the
      workspace-saved pair. Add
      `client_id` to the order destination when the order belongs to a client
      workspace; omit it for the main workspace.
      PlusVibe setup requires `api_key` and the remote `workspace_id`. PlusVibe
      orders and pool attach use that API key and need no login. Its login
      email and password are optional, but must be sent together. Instantly
      login credentials belong on an order destination.
  - name: Bundles
    x-group: Bundles
    description: |
      Saved order template sized by monthly sending volume (`bun_…`). Pass
      `bundle_id` on an order instead of custom license counts.

      Lifecycle: [How bundles work](/concepts/bundles).
  - name: Domains
    x-group: Domains
    description: >
      Sending domains in your partner account (`dom_…`). Same ID whether or not

      the domain is on an order.


      **Status values**


      | Value | What it means |

      | --- | --- |

      | `available` | The domain is in inventory but not on an order yet. |

      | `in_progress` | We're setting it up. |

      | `active` | Live and warming or healthy. |

      | `failed` | Something broke that we can't fix automatically. |

      | `action_required` | We need your help (e.g. update nameservers). |


      **Inventory vs connected**


      - `category=inventory` — yours but not on any order. Inventory rows
        don't include `provider`.
      - `category=connected` — on an active order. The row carries the link
        fields `provider`, `customer_id`, `order_id`, `usable_for`, and
        `forwarding_url`.

      **`usable_for` matrix**


      When you check a domain's availability:


      | Who's on the domain | `usable_for` |

      | --- | --- |

      | Nobody, or just Google | `["google", "microsoft"]` |

      | Microsoft (or both) | `["google"]` |

      | Premium / invalid / errored | not orderable; `available: false` with a
      `reason` |


      **Imports and forwarding are jobs**


      Both **import** and **forwarding** are async jobs. Posting to those

      endpoints starts the job and gives you back a row with `status:

      "in_progress"`. Poll the job's GET endpoint to see when it finishes:


      - Import jobs: prefix `imp_…`. Includes the `nameserver_groups` your
        customer needs to set at their registrar.
        - Forwarding jobs: prefix `fwj_…`. Already-correct domains are
          returned in `completed` with newly updated domains.
  - name: Domain pool
    x-group: Domain pool
    description: |
      Assign an exact quantity from pre-warmed Google inventory. Each domain
      needs at least one active Google inbox on a paid Google order (commonly
      two), complete provider mailbox identity, and no explicit burned provider
      result. Attach is all-or-nothing: full quantity or
      `insufficient_inventory` with no pool change. Attach and release are
      async. Poll the resource or subscribe to `pool.*` webhooks.

      Guide: [Pre-warmed pool](/guides/pre-warmed-pool).
  - name: Prewarmed inboxes
    x-group: Prewarmed inboxes
    description: |
      Buy domains whose inboxes Peeker has already warmed. List live stock
      with `GET /prewarmed`, then buy exact domains with
      `POST /prewarmed/purchase`. Each purchase is a normal order (`ord_…`):
      follow it with `GET /orders/{id}` and find it in `GET /orders`.

      Guide: [Prewarmed inboxes](/guides/prewarmed-inboxes).
  - name: Orders
    x-group: Orders
    description: |
      One purchase of domains plus Google and/or Microsoft licenses for one
      customer (`ord_…`). Use a saved `bundle_id` **or** custom license counts,
      never both. Requires `Idempotency-Key`.

      Lifecycle: [How orders work](/concepts/orders).
  - name: Domain swaps
    x-group: Domain swaps
    description: |
      Replace a domain inside an existing order without losing the order
      (`swp_…`). For persona-only changes use `POST /swaps/user_names`.

      Statuses and standard vs premium: [How swaps work](/concepts/swaps).
  - name: Webhooks
    x-group: Webhooks
    description: |
      Signed JSON POSTs for orders, domains, imports, forwarding, pool, and
      swaps. Register the URL and secret in the
      [Partner portal](https://app.peeker.ai/partner/webhooks). Event IDs look
      like `evt_01HZX`.

      Delivery is at least once (up to 5 attempts). Verify `Peeker-Signature`
      and dedupe `Peeker-Event-Id` for at least 24 hours.

      Full catalog: [Webhooks](/webhooks).
paths:
  /domains/purchase:
    post:
      tags:
        - Domains
      summary: Buy domains without inboxes
      description: |
        Register domains without ordering inboxes. Use this to build up your own
        domain supply, then order inboxes on those domains later with
        `POST /orders`.

        The purchase is a normal order with no mailbox provider. It appears in
        `GET /orders`, sends the `order.in_progress` and `order.completed`
        webhooks (each webhook domain has `provider: null`), and completes once
        every domain is registered. Each domain is charged its registration
        price from your wallet now, and renews yearly from your wallet unless
        you set `auto_renew: false`.

        Each domain must be available and not premium, so check names with
        `POST /domains/availability` first. One purchase can mix TLDs. Every
        domain is bought or none is: an unavailable name or a name already in
        an active order rejects the whole request without charging.

        `workspace_id` is optional. Send it to assign the domains to that
        workspace (and its customer); omit it to keep them in your organization
        unassigned. A later `POST /orders` for the same workspace or customer
        can use these domains.

        Requires a live key with `full` permissions and an `Idempotency-Key`.
        Repeating a request with the same key and body returns the same order
        without charging again. Sandbox keys return `403 forbidden`.
      operationId: purchaseDomains
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - domains
              properties:
                domains:
                  type: array
                  minItems: 1
                  maxItems: 50
                  description: >-
                    Domains to register, each once. Send a domain name, or an
                    object to turn off auto-renew.
                  items:
                    oneOf:
                      - type: string
                        maxLength: 253
                        example: acme-mail.com
                      - type: object
                        additionalProperties: false
                        required:
                          - domain
                        properties:
                          domain:
                            type: string
                            maxLength: 253
                            example: team-acme.com
                          auto_renew:
                            type: boolean
                            default: true
                            description: Renew yearly from your wallet.
                workspace_id:
                  type: string
                  pattern: ^wrk_
                  description: Optional workspace to assign the domains to.
            example:
              domains:
                - acme-mail.com
                - domain: team-acme.com
                  auto_renew: false
              workspace_id: wrk_01J0K1A2B3C4D5E6F7G8H9WRK1
      responses:
        '201':
          description: >-
            Domains charged and the order created. Registration continues in the
            background; follow `data.id` with `GET /orders/{id}`. Retries with
            the same key return this same order.
          headers:
            Peeker-Request-Id:
              $ref: '#/components/headers/PeekerRequestId'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: >-
            Your wallet cannot pay for the purchase within its floor and current
            top-up policy. Nothing is charged or created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            The Idempotency-Key was used with a different body, or a request
            with this key is still in progress. For idempotency_in_progress,
            retry the unchanged body with the same key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 256
      description: |
        Required for order creation. Pool attach also supports this header for
        durable retries. Workspace creation does not use it. The value is
        unique across the Partner account.
        Reuse it only with the same endpoint and unchanged request body. When
        retrying an Instantly order after
        `422 provider_login_credentials_required`, you may add or replace only
        `destination.login_credentials`; every other field must stay unchanged.
        For a Smartlead Microsoft order with that error, repair the
        target through `POST /workspaces`, then retry the unchanged order with
        the same key.
        Retry `503 provider_unavailable` or `500 internal_error` with the same
        key and unchanged body.
        After pool attach returns `409 insufficient_inventory`, wait for pool
        inventory to be replenished, then retry the unchanged body with the
        same key. After `422 provider_login_credentials_required` or
        `422 provider_credentials_invalid`, repair the target workspace, then
        retry the unchanged body with the same key.
  headers:
    PeekerRequestId:
      description: Stable request identifier. Log it with the status and response body.
      schema:
        type: string
        example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - data
      properties:
        data: {}
    Order:
      allOf:
        - $ref: '#/components/schemas/OrderSummary'
        - type: object
          required:
            - domains
            - personas
          properties:
            costs:
              type: object
              required:
                - total_cents
                - currency
                - line_items
              properties:
                total_cents:
                  type: integer
                  nullable: true
                  example: 36800
                currency:
                  type: string
                  example: usd
                line_items:
                  type: array
                  items:
                    $ref: '#/components/schemas/OrderLineItem'
            domains:
              type: object
              required:
                - registered
                - imported
              properties:
                registered:
                  type: array
                  items:
                    type: string
                  example:
                    - domain-01.com
                    - domain-02.com
                imported:
                  type: array
                  items:
                    type: string
                  example:
                    - team-acme.com
            personas:
              type: array
              items:
                type: object
                required:
                  - first_name
                  - last_name
                  - profile_picture_url
                properties:
                  first_name:
                    type: string
                    example: Sam
                  last_name:
                    type: string
                    example: Lee
                  profile_picture_url:
                    type: string
                    nullable: true
                    example: https://example.com/sam.jpg
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Stable machine-readable code. Branch on this field.
              enum:
                - invalid_request
                - unauthorized
                - forbidden
                - not_found
                - rate_limited
                - provider_not_supported
                - provider_mismatch
                - provider_credentials_invalid
                - provider_login_credentials_required
                - provider_unavailable
                - emailbison_super_admin_key
                - smartlead_connection_required
                - smartlead_client_id_required
                - smartlead_client_not_found
                - idempotency_key_required
                - idempotency_conflict
                - idempotency_in_progress
                - workspace_promotion_required
                - workspace_credentials_conflict
                - workspace_sync_unavailable
                - order_shape_conflict
                - domain_count_mismatch
                - insufficient_inventory
                - domain_not_imported
                - domains_not_submittable
                - premium_domain_not_supported
                - domain_not_usable_for_provider
                - domain_already_in_active_order
                - internal_error
              example: emailbison_super_admin_key
            message:
              type: string
              description: Human-readable explanation. Wording may change.
              example: >-
                Use an EmailBison workspace/user API key; super-admin keys are
                not accepted.
            request_id:
              type: string
              description: >-
                Stable request identifier, identical to the `Peeker-Request-Id`
                response header.
              example: 550e8400-e29b-41d4-a716-446655440000
            field:
              type: string
              description: Dot path to the invalid request property, when applicable.
              example: credentials.api_key
            details:
              type: object
              additionalProperties: true
              description: Structured context specific to `error.code`.
    OrderSummary:
      type: object
      required:
        - id
        - customer_id
        - smartlead_client_id
        - origin
        - status
        - domain_count
        - costs
        - renews_at
        - created_at
      properties:
        id:
          type: string
          example: ord_01HZX0OR1A2B3C4D5E6F7G8H
        customer_id:
          type: string
          nullable: true
          pattern: ^cus_
          example: cus_01HZX0C6Z3K4M5N6P7Q8R9S0
        bundle_id:
          type: string
          nullable: true
          example: bun_01HZX0BU1A2B3C4D5E6F7G8H
        smartlead_client_id:
          type: string
          nullable: true
          description: Smartlead client ID for this order, or `null`.
          example: '301'
        destination:
          $ref: '#/components/schemas/Destination'
          description: >-
            Workspace target used for this order (may be missing on very old
            orders).
        origin:
          type: string
          enum:
            - api
            - dashboard
          description: >-
            `api` when the purchase was made through the Partner API.
            `dashboard` for purchases made in the Peeker dashboard. A
            replacement order takes the origin of the purchase it replaces.
          example: api
        status:
          type: string
          enum:
            - in_progress
            - completed
            - failed
            - action_required
            - cancel_scheduled
            - cancelled
          example: in_progress
        processing:
          type: object
          description: >-
            Funding and setup progress. Omitted after order completion or
            cancellation.
          required:
            - phase
            - funding_deadline_at
            - error
          properties:
            phase:
              type: string
              enum:
                - queued
                - waiting_for_funds
                - preparing
                - provisioning
                - failed
            funding_deadline_at:
              type: string
              format: date-time
              nullable: true
            error:
              type: string
              nullable: true
        domain_count:
          type: integer
          example: 2
        costs:
          type: object
          required:
            - total_cents
            - currency
          properties:
            total_cents:
              type: integer
              nullable: true
              description: Null when billing records cannot establish the amount.
              example: 6800
            currency:
              type: string
              example: usd
        renews_at:
          type: string
          nullable: true
          format: date-time
          description: Next renewal date for the order. `null` until billing is created.
          example: '2026-06-08T12:00:00Z'
        created_at:
          type: string
          format: date-time
          example: '2026-05-08T12:00:00Z'
    OrderLineItem:
      type: object
      required:
        - type
        - quantity
        - amount_cents
      properties:
        type:
          type: string
          enum:
            - domain_registration
            - google_license
            - microsoft_license
          example: google_license
        quantity:
          type: integer
          example: 4
        amount_cents:
          type: integer
          nullable: true
          description: Null when the stored item price is missing.
          example: 10000
    Destination:
      description: |
        Provider workspace target that received or will receive the mailboxes.
        The JSON field name is `destination`.
      oneOf:
        - $ref: '#/components/schemas/EmailBisonDestination'
        - $ref: '#/components/schemas/InstantlyDestination'
        - $ref: '#/components/schemas/SmartleadDestination'
        - $ref: '#/components/schemas/PlusVibeDestination'
      discriminator:
        propertyName: provider
        mapping:
          emailbison: '#/components/schemas/EmailBisonDestination'
          instantly: '#/components/schemas/InstantlyDestination'
          smartlead: '#/components/schemas/SmartleadDestination'
          plusvibe: '#/components/schemas/PlusVibeDestination'
    EmailBisonDestination:
      title: Existing EmailBison workspace
      type: object
      additionalProperties: false
      required:
        - provider
        - workspace_id
      properties:
        provider:
          type: string
          enum:
            - emailbison
        workspace_id:
          type: string
          pattern: ^wrk_
          description: Peeker workspace ID (`wrk_…`).
          example: wrk_01HZX0EB1A2B3C4D5E6F7G8H
    InstantlyDestination:
      title: Existing Instantly workspace
      type: object
      additionalProperties: false
      required:
        - provider
        - workspace_id
      properties:
        provider:
          type: string
          enum:
            - instantly
        workspace_id:
          type: string
          pattern: ^wrk_
          description: Peeker workspace ID (`wrk_…`).
          example: wrk_01HZX0JN1A2B3C4D5E6F7G8H
    SmartleadDestination:
      title: Existing Smartlead workspace
      type: object
      additionalProperties: false
      required:
        - provider
        - workspace_id
      properties:
        provider:
          type: string
          enum:
            - smartlead
        workspace_id:
          type: string
          pattern: ^wrk_
          description: Peeker ID for the connected Smartlead main workspace.
          example: wrk_01HZX0SK1A2B3C4D5E6F7G8H
        client_id:
          type: string
          pattern: ^[1-9][0-9]*$
          maxLength: 64
          description: Optional Smartlead client ID. Omit it for the main workspace.
          example: '366903'
    PlusVibeDestination:
      title: Existing PlusVibe workspace
      type: object
      additionalProperties: false
      required:
        - provider
        - workspace_id
      properties:
        provider:
          type: string
          enum:
            - plusvibe
        workspace_id:
          type: string
          pattern: ^wrk_
          description: |
            Peeker workspace ID (`wrk_…`), not PlusVibe’s remote ID.
          example: wrk_01HZX0PV1A2B3C4D5E6F7G8H
  responses:
    InvalidRequest:
      description: Bad request body, or fields that don’t belong to this provider.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Valid key, but it doesn’t allow this action.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: >-
        A referenced workspace, customer, bundle, domain, or order was not
        found.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: >-
        Too many requests. Wait `Retry-After` seconds (also in
        `error.details.retry_after_seconds`), then retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying; capacity is not reserved.
          schema:
            type: integer
            minimum: 1
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: Unexpected server error. Retry with backoff and keep the request ID.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Partner API key (`pk_live_…` or `pk_test_…`).
      x-default: Bearer pk_test_<your-test-key>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.