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. An acquired list must pass paid validation before it can be sent to.

mapping
object

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

options
object

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.