Peeker Partner API

Use this flow when the customer already owns the domains. Import them first, then submit the order to an existing workspace target.

1. Import (sync, up to 25)

POST /domains/import runs before the response returns. The first request runs the import before returning. Repeating the same normalized set of domains reuses its current non-failed job, including when submitted through /domains/import/jobs. Domain order and letter case do not affect this identity. A replay can return in_progress while the original request is running; poll GET /domains/import/jobs/{id} for the final result. After a timeout or server error, repeating the request recovers an existing running or completed job without running the provider again. If the job is failed, fix its reported cause and submit the same domains to start a new attempt with a new job ID. The old job stays readable by its original ID. Concurrent submissions share the new attempt while it is running. An action_required job with mixed success and failure is still replayed. Submit only its failed domains to retry those imports without repeating the successful ones. Poll a known job ID when you only want its status; submitting again after another terminal failure starts another attempt.

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

{
	"data": {
		"id": "imp_01HZX0IM1A2B3C4D5E6F7G8H",
		"status": "completed",
		"submitted_count": 2,
		"completed_count": 2,
		"failed_count": 0,
		"nameserver_groups": [
			{
				"nameserver_one": "helena.ns.cloudflare.com",
				"nameserver_two": "idris.ns.cloudflare.com",
				"domains": ["acme-mail.com", "team-acme.com"]
			}
		],
		"failed": [],
		"created_at": "2026-05-08T12:00:00Z"
	}
}

Show nameserver_groups to the customer when they need to update DNS at their registrar. A successful import can still include those nameservers. For batches of up to 500 domains, use POST /domains/import/jobs (returns 202 with in_progress). Poll or subscribe to domain_import.*.

2. Understand terminal statuses

Status	Meaning
`completed`	Submitted domains imported successfully
`action_required`	Some imported and some failed. Inspect `failed` and counts.
`failed`	The import run failed

An import may partially succeed. Read completed_count, failed_count, and failed. Listen for:

domain_import.completed
domain_import.action_required
domain_import.failed

3. Submit the order

After the required domains are imported, use POST /orders with an existing workspace target.

Strict Smartlead order

{
	"destination": {
		"provider": "smartlead",
		"workspace_id": "wrk_01HZX0SK1A2B3C4D5E6F7G8H"
	},
	"order": {
		"google_licenses": 2,
		"domains": ["acme-mail.com", "team-acme.com"],
		"personas": [
			{ "first_name": "Alex", "last_name": "Rivera" },
			{ "first_name": "Sam", "last_name": "Lee" }
		]
	}
}

Send a unique Idempotency-Key for this order. Use the same key only when retrying the same request. See How domains work and How orders work.

Provider setup and ordering

See workspace creation and order shapes.

Webhooks

Verify signatures and handle duplicate delivery safely.

​1. Import (sync, up to 25)

​2. Understand terminal statuses

​3. Submit the order

Provider setup and ordering

Webhooks

1. Import (sync, up to 25)

2. Understand terminal statuses

3. Submit the order