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

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.
The initial response identifies the queued job; acceptance does not mean the domains have finished importing. Fetch the completed result:
Example after completion:
Show 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.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
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.
Last modified on October 24, 2026