Upsert Contact

Create or update a contact by email in a single call.

POST /api/v1/contacts/upsert

The most commonly used endpoint for integrations. If the email exists, the contact is updated — merging custom fields and preserving existing values for unset fields.

Parameters

Same as Create Contact — email is required, all other fields are optional.

Merge Behavior

• phone, firstName, lastName — updates only if provided (non-null)
• customFields — deep-merged with existing fields
• tags — replaces existing tags only if provided and non-empty
• emailSubscriptionStatus, whatsappSubscriptionStatus — updates only if provided

Example

curl -X POST /api/v1/contacts/upsert \
  -H "x-api-key: mndr_..." \
  -H "Content-Type: application/json" \
  -d '{
  "email": "jane@example.com",
  "firstName": "Jane",
  "customFields": { "plan": "pro" }
}'

{
  "contact": { ... },
  "created": true
}

{
  "contact": { ... },
  "created": false
}