Skip to main content
POST
Create Subscriber Import
Use this endpoint for CRM migrations and first-list onboarding instead of issuing one create request per contact. The request returns 202 immediately; use the returned import ID with Get Subscriber Import.

Permissions

The API key needs subscribers:write. Supplying listIds also requires lists:write; requesting sequence enrollment or double-opt-in delivery requires automations:trigger.
object[]
required
One to 5,000 records. Every record requires an email or a phone (phone-only records import as SMS contacts) and may include externalId, firstName, lastName, phone, status, tags, typed customAttributes, and createdAt.
string
ISO 8601 date this contact originally signed up on the source platform. Preserves their real history so date-relative segments are correct right after the import. An existing contact’s date only ever moves earlier. If any record carries an unusable value the whole request is rejected with a 400 naming the row, so you never end up with a half-imported list.
string
default:"skip"
skip, merge, or overwrite.
string
Caller-owned key (1-255 characters; blank keys are rejected with a 400) that makes retrying this request safe. The key is scoped to the request content: resending the same request returns the already-queued import with deduplicated: true (as a 200, or as a 202 while the import is still starting up), while different content under the same key queues a new import rather than silently discarding the corrected data. Use it whenever a timeout or retry loop could resend the same import - pipelines should derive it from the sync run (e.g. nightly-sync-2026-08-25). Note this differs from the transactional send Idempotency-Key header, which rejects key reuse with different content.
string[]
List IDs to apply to every imported subscriber. Every ID must belong to the authenticated workspace.
string
default:"default"
default obeys the workspace setting, confirmed imports contacts whose consent has already been verified, and double_opt_in queues confirmation delivery. Keys without automations:trigger must use confirmed for active consented contacts.
boolean
default:"false"
Enroll matching subscribers after import. Requires automations:trigger.
string
Two-letter country code used to normalize national-format phone numbers.
Apply the supplied SMS consent to imported phone numbers. Never infer this from phone presence.
A 503 in this form means another request currently owns the short enqueue lease; honor Retry-After and resend the identical request. It does not mean the import failed, and the deterministic import and job IDs keep the retry safe.
A completed import can contain row failures. Always inspect failedCount and failedReasons before treating the migration as successful.