Skip to main content

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.

When a domain’s deliverability is deteriorating, a swap replaces it with a fresh one inside the existing order — keeping the workspace, the customer, and the rest of the order intact. Two flavors:
  • Standard. Old domain retired immediately. Lower cost, fastest cutover, brief send-pause on that one domain.
  • Premium. Old domain stays warm 14 days alongside the new one. No sending interruption; smoother handoff during warmup.
To rename the people on a domain (not the domain itself), use Changing user names on active orders instead.

​
Steps in detail

1. Choose standard or premium

You want to…UseWhy
Replace one domain, no sending gapPremiumOld domain stays warm 14 days; smoother handoff.
Replace one domain, can absorb a brief pauseStandardLower cost, immediate cutover.
Replace many domains at onceCancel order, place newSwaps are one domain at a time.
POST /swaps takes type (standard or premium), domain_id, and replacement_domain. Same response shape for both types — only type differs. The replacement_domain must be a domain Peeker can either buy from a partner registrar (registrar source) or one the customer has already imported (imported source).
cURL
curl -X POST "https://api.peeker.ai/api/partner/v1/swaps" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "type":               "premium",
    "domain_id":          "dom_01HZX0D01…",
    "replacement_domain": "acme-fresh.com"
  }'
201 Created
{
  "data": {
    "id":                 "swp_01HZX0SW1A2B3C4D5E6F7G8H",
    "type":               "premium",
    "domain_id":          "dom_01HZX0D01A2B3C4D5E6F7G8H",
    "replacement_domain": "acme-fresh.com",
    "status":             "created",
    "created_at":         "2026-05-08T12:00:00Z"
  }
}
Poll GET /swaps/{id} or listen for the webhooks below.
cURL
curl -X GET "https://api.peeker.ai/api/partner/v1/swaps/swp_01HZX0SW…" \
  -H "Authorization: Bearer pk_test_<your-key>"

created  →  in_progress  →  completed
                       ↘  failed
                       ↘  action_required
EventFires when
swap.createdImmediately after POST /swaps accepts.
swap.in_progressWorkers picked it up.
swap.completedNew domain is live; old one detached (or kept warm for premium).
swap.failedSwap hit an unrecoverable error. Read the next swap payload via GET /swaps/{id}.
swap.action_requiredSwap is blocked on partner input (e.g. replacement domain isn’t imported).
The most common reason: the replacement domain isn’t imported yet. Run Importing domains & ordering for the replacement (just the import portion — no need for a new order), then call POST /swaps again. The original swap will resolve automatically once the replacement is verified, or you can cancel it and start fresh.
Webhook · swap.action_required
{
  "id":         "evt_01HZX0EVFA2B3C4D5E6F7G8H",
  "type":       "swap.action_required",
  "created_at": "2026-05-08T12:30:00Z",
  "data": {
    "swap": {
      "id":                 "swp_01HZX0SW1A2B3C4D5E6F7G8H",
      "type":               "premium",
      "domain_id":          "dom_01HZX0D01A2B3C4D5E6F7G8H",
      "replacement_domain": "acme-fresh.com",
      "status":             "action_required"
    }
  }
}

​
What’s next

Changing user names on active orders

Same domain, different people on the inboxes — for team rotations.

Best practices

Pending actions, webhook hygiene, idempotent retries.
Last modified on May 14, 2026