Create or update contacts

Upserts a single contact OR a batch ({ contacts: [...] }, up to 1000 rows). Unknown custom fields auto-create field definitions on the brand, typed from the batch (native booleans/numbers, ISO-date strings → date, anything else string). fieldsCreated names only the definitions this request created: when two requests create the same new field at once, the first definition wins and the values in the other request are coerced or refused against it, exactly as if it had been sent second. Create the field first with POST /v1/fields to pin its type.

Custom-field names are folded to one key: words split at spaces, _, - and a lower-to-upper letter change, then joined camelCase (Plan, PLAN and plan are the field plan; team_size and Team Size are teamSize). A key written under its folded name adds a FIELD_NAME_NORMALIZED warning (original, normalized). Two keys that fold to one field (plan and Plan) would lose one value, so they are a 422 FIELD_NAME_COLLISION on a single upsert (nothing written) and a per-row errors[] entry (code: FIELD_NAME_COLLISION) in a batch.

Custom-field values are coerced to the definition’s type (dates → epoch ms, "1,234" → 1234, yes/no → booleans). A value that cannot be coerced ("$49" in a number field) is a 409 FIELD_TYPE_MISMATCH on a single upsert and a per-row errors[] entry (code: FIELD_TYPE_MISMATCH, field) in a batch — the other rows still land. A value that was converted adds one warnings[] entry per field (code: FIELD_TYPE_COERCED, field, from, to); a date written to a date field is not reported. A customFields key is never stored under a core field name. One whose loss would change the contact (subscribed, First Name, consent, a suppression flag or domain opt-out, or an email naming another address) is a 422 CORE_FIELD_IMMUTABLE on a single upsert (nothing written) and a per-row errors[] entry (code: CORE_FIELD_IMMUTABLE, field) in a batch; send firstName, lastName, subscribed and consent at the top level. A key naming a field Brew manages (createdAt, validationStatus) is dropped with a warnings[] entry (code: CORE_FIELD_IGNORED, field) and the contact is still written, and an email key repeating the contact address is ignored.

Dates: a JSON number is epoch milliseconds. A string may be ISO (2026-04-03, with or without a time and offset), a Unix timestamp in seconds (10 digits) or milliseconds (13), a month name (3 Apr 2026, April 3, 2026, 03-Apr-26), year-first (2026/04/03), compact (20260403), month and year read as the 1st (2026-04), dotted day-first (03.04.2026), or a slash or dash date. A slash or dash date with a day over 12 reads that way (13/04/2026 is 13 April). One that reads either way (03/04/2026) follows the day/month order the batch’s other dates in that field prove, else month/day, with a warnings[] entry (code: DATE_ORDER_ASSUMED, field). Send YYYY-MM-DD to be unambiguous.

Optional consent: { source: "api" | "form" | "import", capturedAt?, policyVersion?, evidence? } records marketing consent provenance on the contact (per row, or once at batch level as the default). It never changes subscribed. An inline marketing send later needs the contact to be subscribed, and warns when no record exists.

subscribed: false unsubscribes the contact, new or existing. subscribed: true only applies to a NEW contact: Brew never re-subscribes a contact who opted out, so a single upsert asking for it is a 422 RESUBSCRIBE_NOT_ALLOWED (nothing written), and a batch row keeps its other fields and adds a warnings[] entry (code: RESUBSCRIBE_SKIPPED, email).

Single: 201 with { contact, created, fieldsCreated, warnings }. Batch: 200 with { summary, fieldsCreated, errors, warnings } — or 207 when some rows failed (per-row errors in errors[]).