Subscribers
Create Subscriber Import
Queue an asynchronous import of up to 5,000 full subscriber records
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 needssubscribers: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.
boolean
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.Create Subscriber Import