Skip to main content
POST
Bulk-import contacts from JSON

Authorizations

Authorization
string
header
default:Bearer brew_your_api_key
required

Send your Brew API key as Authorization: Bearer brew_xxx.

Headers

X-Brand-Id
string

The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise 400 BRAND_ID_REQUIRED — there is no default brand); list ids with GET /v1/brands. Brand-scoped credentials may omit it, and sending a different brand returns 403 BRAND_SCOPE_MISMATCH. A brand outside your organization returns 404 BRAND_NOT_FOUND.

Required string length: 1 - 64

Body

application/json
contacts
object[]
required
Required array length: 1 - 1000 elements
validate
boolean

Optional deliverability check on ingestion. When true, each imported address is validated with the provider and the verdict is saved to the contact’s validationStatus. Imports of at most 100 submitted contacts validate inline, metered at 2 credits per submitted contact on a successful response, including rows that fail. Larger imports write first and use a background validation workflow billed per address as it runs; validationJobId is returned when a job is queued.

Default consent record for every row that does not carry its own consent (typically { "source": "import" }).

fileName
string

Name this batch is listed under in Import History (usually the source file name, e.g. customers.csv), also stamped on every contact it writes as csvFileName. A path keeps only its last segment.

Required string length: 1 - 255
dryRun
boolean

When true, returns what this import would return and writes nothing: no contacts, fields, Import History entry or importId; validate is skipped and nothing is charged.

onConflict
enum<string>

upsert (default) updates existing contacts; skip only creates missing ones, leaving each existing contact unchanged (counted in summary.skipped, with a CONTACT_EXISTS_SKIPPED warning).

Available options:
upsert,
skip

Response

Import summary (all rows valid).

summary
object
required
fieldsCreated
string[]
required
errors
object[]
required
warnings
object[]
required
validation
object
validationJobId
string
importId
string

This batch's Import History id. Each contact it wrote carries it as importId until a later import touches that contact, so a contact filter on importId lists them. Absent on a dry run.

dryRun
enum<boolean>

Present on a dry run: the counts say what the import would do, and nothing was written.

Available options:
true