1. Start an import (up to 500)
POST /domains/import/jobs returns 202 and processes domains in the background.
Save the returned imp_… ID. New jobs start with status: "in_progress".
Repeating the same normalized domain set reuses its current non-failed job;
domain order and letter case do not change its identity. A replay retains the
job’s current status, including completed results.
Poll GET /domains/import/jobs/{id} or listen for domain_import.* webhooks
before proceeding to order creation. List past imports with GET /domains/import/jobs.
The list also shows imports started in the Peeker dashboard, marked origin: "dashboard".
API imports are marked origin: "api".
If you lost a job’s ID, add ?domain=acme-mail.com to find the jobs for that domain.
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.
nameserver_groups to the customer when they need to update DNS at their
registrar. A successful import can still include those nameservers.
nameserver_groups covers the job’s first 5,000 domains, and failed lists the
first 5,000 failures anywhere in the job (rows in GET /domains/import/jobs
embed groups from at most 500 domains). When results_truncated is true, page
GET /domains/import/jobs/{id}/results for every domain, its nameservers, and
any failure reason. Counts are always exact.
2. Understand terminal statuses
An import may partially succeed. Read
completed_count, failed_count, and
failed.
Listen for:
domain_import.completeddomain_import.action_requireddomain_import.failed
3. Submit the order
After the required domains are imported, usePOST /orders with an existing
workspace target.
Strict Smartlead order
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.