Upsert Contacts

Bulk creates or updates contacts in an organization.

Optionally, it can opt in contacts to all organization channels or specific channels. Also, the contacts in the list can optionally be associated with a custom object by providing the custom object ID in the top level of the request body and the properties of the custom object in the properties key of each contact. А contact's relationship with a custom object is always one-to-one.

Important: The following fields of a contact are unique and also nullable:

• external_id
• phone
• email

This means that if a contact with the same value for any of these fields already exists in the organization, the contact will be updated instead of created. The following update strategy is applied:

• If a contact is present in the payload where the external_id conflicts with the external_id of an existing contact:
  • If the existing contact has a different email and phone than the new contact, the existing contact will be updated with the new data and the email and phone will be overwritten, as long as no other contact has the same email or phone.
• If a contact is present in the payload where the phone conflicts with the phone of an existing contact:
  • If the existing contact has the same external_id as the new contact or its value is not set, the existing contact will be updated with the new data.
  • If the existing contact has a different external_id than the new contact, a new contact without a phone will be created.
• If a contact is present in the payload where the email conflicts with the email of an existing contact:
  • If the existing contact has the same external_id and phone as the new contact or their values are not set, the existing contact will be updated with the new data.
  • If the existing contact has a different external_id and phone than the new contact, a new contact without an email will be created.