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[]
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 completed import can contain row failures. Always inspect failedCount and failedReasons before treating the migration as successful.