Creates a new contact or updates an existing one based on the provided identifiers.
This endpoint intelligently handles conflicts and merges data according to specified rules.

How Identifiers Work

You must provide at least one identifier:

• contact_id: Internal Customerly ID (if specified, must exist)
• custom_contact_id: Your custom identifier
• email: Email address
• whatsapp_number: WhatsApp number in E.164 format (+123456789)

Conflict Detection

If multiple identifiers are provided, they must either:

• All point to the same contact, OR
• Point to no existing contact (new contact creation), OR
• contact_id exists and other identifiers are "free" (will update the contact_id contact)

If different identifiers point to different contacts, the request will fail with a conflict error.

Role Handling

• Lead → User promotion: If a lead exists, and you specify role: "user", it will be promoted to user
• User → Lead: Not allowed. If a user exists, and you specify role: "lead", the contact remains a user

Attributes and Tags

• Attributes: Merged incrementally (only specified attributes are created/updated, others remain unchanged)
• Tags: Added incrementally (new tags are added, existing tags are kept, no removal)

Response Data

The endpoint returns the complete contact object including:

• All contact basic information (name, email, role, created date, etc.)
• All attributes (both updated and unchanged ones)
• All tags associated with the contact
• Custom contact ID, WhatsApp number, and other identifiers
• HTTP status: 201 Created for new contacts, 200 OK for updated contacts

Further Reading

Contact properties can be powerful tools in managing and understanding your customer base.
For a detailed guide on how to utilize contact properties within Customerly, including creating
custom properties and managing default ones, refer to:

A Complete Guide About Contact Properties

This guide provides step-by-step instructions and best practices for working with contact
properties in your Customerly account.