Upsert Contact

Creates a contact, or updates an existing one when a match is found based on the contact's identifiers.

Matching uses externalId, email.email, and phone.phone to find an existing contact. See contact matching for the detailed matching rules.

Upsert modes: Set upsertMode to control how an existing contact is updated:

• OVERWRITE (default): Replaces existing field values.
• APPEND: Sets a non-array field only if it doesn't already have a value, and appends to array fields.
• OVERWRITE_APPEND_ARRAYS: Overwrites non-array fields and appends to array fields. email/additionalEmails and phone/additionalPhones are each treated as a single array field: the incoming value is set as email/phone only if none exists yet, otherwise it's appended to additionalEmails/additionalPhones.

Member contacts: Set updateMember to true when upserting a contact that is a site member.

The response's action field indicates whether the contact was CREATED or UPDATED.

Image upload: When you provide an image URL, the image is uploaded asynchronously and an imageUploadId is returned for tracking upload progress. Call Get Contact Image Upload Status to monitor the upload.

To create or update multiple contacts in a single request, call Bulk Upsert Contacts.