Peeker Partner API

Use this endpoint to change forwarding on domains that are already live. For a new order, set forwarding_url in the order instead. Forwarding is always an async job (fwj_…). See Async jobs.

Start the job

POST /domains/forwarding accepts up to 25 domains. Each entry can be a dom_... ID or a domain name.

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

The API returns a job:

{
	"data": {
		"id": "fwj_01HZX0FW1A2B3C4D5E6F7G8H",
		"status": "in_progress",
		"completed_count": 0,
		"failed_count": 0,
		"forwarding_url": "https://acme.com",
		"completed": [],
		"failed": [],
		"created_at": "2026-05-08T12:00:00Z"
	}
}

Track the result

Poll GET /domains/forwarding/{id} until the status is completed, partial_success, or failed.

Status	Meaning	Webhook
`completed`	Every domain succeeded	`domain.forwarding_updated`
`partial_success`	Some domains succeeded	`domain.forwarding_updated`
`failed`	Every domain failed	`domain.forwarding_failed`

Already-correct domains are returned in completed.

{
	"data": {
		"id": "fwj_01HZX0FW1A2B3C4D5E6F7G8H",
		"status": "partial_success",
		"completed_count": 1,
		"failed_count": 1,
		"forwarding_url": "https://acme.com",
		"completed": ["acme-mail.com"],
		"failed": [
			{
				"domain": "team-acme.com",
				"reason": "not_connected_to_cloudflare"
			}
		],
		"created_at": "2026-05-08T12:00:00Z",
		"completed_at": "2026-05-08T12:01:30Z"
	}
}

Public failure reasons are domain_not_found, not_connected_to_cloudflare, and forwarding_update_failed. Correct the issue, then submit a new job for the failed domains.

Place an order

Set forwarding while creating the order.

Webhooks

Verify signatures and handle duplicate delivery.

​Start the job

​Track the result

Place an order

Webhooks

Start the job

Track the result