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 customer changes their marketing site (or you need to move forwarding off a stale URL), POST /domains/forwarding repoints any number of domains at one new URL in a single call. The job runs async; domains already pointed at the URL are returned as completed.
For a fresh order, set forwarding_url on POST /orders instead — that handles forwarding inline as part of provisioning. This guide is for changing forwarding on domains that are already live.

​
Steps in detail

1. Submit the bulk change

Each row in domains[] can be a dom_… ID or a raw domain name — both resolve to the same domain row. The whole request returns quickly with an fwj_… job ID; the actual work runs async.
cURL
curl -X POST "https://api.peeker.ai/api/partner/v1/domains/forwarding" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "domains":        ["acme-mail.com", "team-acme.com", "news-acme.com"],
    "forwarding_url": "https://acme.com/inbox-redirect"
  }'
202 Accepted
{
	"data": {
		"id": "fwj_01HZX0FW1A2B3C4D5E6F7G8H",
		"status": "in_progress",
		"completed_count": 0,
		"failed_count": 0,
		"forwarding_url": "https://acme.com/inbox-redirect",
		"completed": [],
		"failed": []
	}
}
Poll GET /domains/forwarding/{id} until the job reaches one of three terminal states:
  • completed — every submitted domain succeeded.
  • partial_success — some completed and some failed.
  • failed — the whole job hit an unrecoverable error.
Already-correct domains are included in completed with newly updated domains.
cURL
curl -X GET "https://api.peeker.ai/api/partner/v1/domains/forwarding/fwj_01HZX0FW…" \
  -H "Authorization: Bearer pk_test_<your-key>"
200 OK · completed
{
	"data": {
		"id": "fwj_01HZX0FW1A2B3C4D5E6F7G8H",
		"status": "completed",
		"completed_count": 3,
		"failed_count": 0,
		"forwarding_url": "https://acme.com/inbox-redirect",
		"completed": ["acme-mail.com", "team-acme.com", "news-acme.com"],
		"failed": [],
		"created_at": "2026-05-08T12:00:00Z",
		"completed_at": "2026-05-08T12:01:30Z"
	}
}
Forwarding job webhooks use the same data shape as GET /domains/forwarding/{id}. That makes webhook handling and polling use the same parser.
{
	"id": "evt_01HZX0EV9A2B3C4D5E6F7G8H",
	"type": "domain.forwarding_updated",
	"created_at": "2026-05-08T12:01:30Z",
	"data": {
		"id": "fwj_01HZX0FW1A2B3C4D5E6F7G8H",
		"status": "completed",
		"completed_count": 3,
		"failed_count": 0,
		"forwarding_url": "https://acme.com/inbox-redirect",
		"completed": ["acme-mail.com", "team-acme.com", "news-acme.com"],
		"failed": [],
		"created_at": "2026-05-08T12:00:00Z",
		"completed_at": "2026-05-08T12:01:30Z"
	}
}
ReasonWhat to do
dns_lookup_failedThe customer’s domain isn’t resolving (likely a registrar issue). Re-import or wait.
target_unreachableThe forwarding URL returned 5xx during validation. Check the URL is live and https.
invalid_targetURL is malformed or not http(s)://. Send a corrected URL on a fresh forwarding job.
Already-correct domains are idempotent — safe to re-run the same job; they return in completed.

​
Things to handle in production

  • Mixing dom_… IDs and raw names. Both resolve. If you have the IDs already (from a previous order response), they’re slightly faster — Peeker skips the lookup.
  • Per-domain overrides on a fresh order. If you’re placing a new order and most domains share one forwarding URL but one is different, set forwarding_url on POST /orders and pass an override object for the odd domain — no separate POST /domains/forwarding call needed. Example in Buying domains & ordering.
  • Rate budget. A bulk change of 100 domains in one call burns one rate-limit token (out of 600/min). Cheaper than 100 separate calls.

​
What’s next

Buying domains & ordering

Set forwarding inline when you place a fresh order.

Webhooks

Verify forwarding event signatures and dedupe on Peeker-Event-Id.
Last modified on May 14, 2026