Peeker Partner API

Use this flow when Peeker should buy the domains. Create the provider workspace target first, then submit the order with its wrk_... ID. Need names from a keyword first? Use Generate domain names.

1. Check availability

Send up to 50 domains per call.

curl -X POST "https://api.peeker.ai/partner/v1/domains/availability" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H "Content-Type: application/json" \
  --data '{ "domains": ["acme-mail.com", "team-acme.com"] }'

An available row includes usable_for:

{
	"data": {
		"domains": [
			{
				"domain": "acme-mail.com",
				"available": true,
				"price_cents": 1300,
				"renewal_price_cents": 1500,
				"currency": "usd",
				"usable_for": ["google", "microsoft"]
			}
		]
	}
}

Choose enough eligible domains for the order. Microsoft domains must include microsoft in usable_for. Sizing rules: How orders work.

2. Submit the order

This strict example assumes the PlusVibe workspace target already exists. See Provider setup and ordering for setup.

curl -X POST "https://api.peeker.ai/partner/v1/orders" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H "Idempotency-Key: checkout_01HZX0ORDER" \
  -H "Content-Type: application/json" \
  --data '
{
  "destination": {
    "provider": "plusvibe",
    "workspace_id": "wrk_01HZX0PV1A2B3C4D5E6F7G8H"
  },
  "order": {
    "google_licenses": 2,
    "forwarding_url": "https://acme.com",
    "domains": ["acme-mail.com"],
    "personas": [
      { "first_name": "Alex", "last_name": "Rivera" }
    ]
  }
}'

google_licenses: 2 creates two Google inboxes on this domain. Peeker then validates availability and pricing before creating the order. With a sandbox key, generated names use the same deterministic availability rules here, so a generated name remains orderable unless another order uses it first. If validation fails, the provider is not called and no order is created.

3. Track completion

Subscribe to order.in_progress, order.completed, and order.failed. Poll GET /orders/{order_id} for the latest state. If status is action_required, poll GET /orders/pending. There is no order.action_required webhook.

order.in_progress → order.completed
                  ↘ order.failed
                  ↘ action_required (poll GET /orders/pending)

Cancel events: order.cancel_scheduled, order.domains_cancelled, order.cancelled. See How orders work.

Buy domains without inboxes

To buy domains now and order inboxes later, send the available names to POST /domains/purchase. workspace_id is optional.

curl -X POST "https://api.peeker.ai/partner/v1/domains/purchase" \
  -H "Authorization: Bearer pk_live_<your-key>" \
  -H "Idempotency-Key: domains_01HZX0PURCHASE" \
  -H "Content-Type: application/json" \
  --data '{ "domains": ["acme-mail.com", "team-acme.com"], "workspace_id": "wrk_01HZX0SK1A2B3C4D5E6F7G8H" }'

The response is the new order (201). Each domain is charged from your wallet and renews yearly unless you send { "domain": "...", "auto_renew": false }. The order sends the same webhooks as above and completes once every domain is registered. A later POST /orders for the same workspace or customer can use these domains. Sandbox keys cannot buy domains. Webhook delivery is at least once. Verify the signature and dedupe on Peeker-Event-Id.

Provider setup and ordering

Create a provider workspace target, then order through it.

Webhooks

Event names, signatures, and retry behavior.

​1. Check availability

​2. Submit the order

​3. Track completion

​Buy domains without inboxes