Skip to main content
POST
Import Contacts From A URL

Authorizations

X-API-Key
string
header
required

Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy.

Headers

Idempotency-Key
string

Optional idempotency key: a unique string of 16-200 printable ASCII characters (a UUID is recommended). Retrying the write with the same key within 24 hours returns the stored response of the first call with an X-Idempotent-Replayed: true response header instead of executing it again. Reusing a key with a different request body returns 422 (IDEMPOTENCY_MISMATCH); a duplicate sent while the first call is still running returns 409 with a Retry-After header. Keys are scoped per endpoint and organization.

Required string length: 16 - 200

Body

application/json
source_url
string<uri>
required

HTTPS URL of the CSV. Maximum 50 MB.

name
string

Name for the list this file becomes. Defaults to the file name. The uploaded file IS the list: an import creates one rather than adding to an existing list.

Maximum string length: 255
email_domain_id
string<uuid>

Scopes the list to one sending domain. Omit for an organization-wide list any campaign can use.

acquired
boolean

The addresses were purchased or rented. Acquired lists are not blocked from sending, but they ramp on half the normal warm-up steps.

mapping
object

CSV header to contact field, for example {"Email Address": "email", "First": "first_name"}. Exactly one header must map to email.

Response

Import accepted. Poll the import for progress.

success
boolean
required
data
object
required

One import of a caller-hosted CSV into an email list.