Skip to main content
Version: v3New

Upsert Contact

POST 
/contacts/upsert

The Upsert API will adhere to the configuration defined under the "Allow Duplicate Contact" setting at the Location level. If the setting is configured to check both Email and Phone, the API will attempt to identify an existing contact based on the priority sequence specified in the setting, and will create or update the contact accordingly.

If two separate contacts already exist—one with the same email and another with the same phone—and an upsert request includes both the email and phone, the API will update the contact that matches the first field in the configured sequence, and ignore the second field to prevent duplication.

Request​

Version stringrequired

API Version

Available optionsv3
application/json

Bodyrequired

    firstNamestringnullable

    First name of the contact

    lastNamestringnullable

    Last name of the contact

    namestringnullable

    Full name of the contact

    emailstringnullable

    Email address of the contact

    locationIdstringrequired

    Location Id the contact should be created under

    genderstring

    Gender of the contact

    phonestringnullable

    Phone number of the contact

    address1stringnullable

    Street address of the contact

    citystringnullable

    City of the contact

    statestringnullable

    State of the contact

    postalCodestring

    Postal code of the contact

    websitestringnullable

    Website URL of the contact

    timezonestringnullable

    Timezone of the contact

    dndboolean

    Whether Do Not Disturb is enabled for the contact

    inboundDndSettingsobject

    Inbound DND settings per channel for the contact

    tagsstring[]

    This field will overwrite all current tags associated with the contact. To update a tags, it is recommended to use the Add Tag or Remove Tag API instead.

    customFieldsobject[]

    List of custom field values to assign to the contact

    sourcestring

    Source from which the contact was created

    dateOfBirthobjectnullable

    The birth date of the contact. Supported formats: YYYY/MM/DD, MM/DD/YYYY, YYYY-MM-DD, MM-DD-YYYY, YYYY.MM.DD, MM.DD.YYYY, YYYY_MM_DD, MM_DD_YYYY

    countrystring

    Country code of the contact (ISO 3166-1 alpha-2)

    companyNamestringnullable

    Company name of the contact

    assignedTostring

    User's Id

    createNewIfDuplicateAllowedboolean

    Controls whether to create a new contact or update an existing duplicate. Scenario 1: If this value is true and the location allows duplicate contacts, a new contact will be created immediately without checking for duplicates. Scenario 2: If this value is true but the location does not allow duplicate contacts, this field is ignored and the normal upsert behavior applies: the API will search for an existing duplicate contact, update it if found, or create a new contact if not found. Scenario 3: If this value is false or not provided, the normal upsert behavior applies regardless of the location's duplicate contact setting.

    Default value: false
    dndSettingsobject

    Per-channel DND settings for the contact

application/json

Successful response

Schema
    newboolean

    Whether a new contact was created (true) or an existing one was updated (false)

    contactobject

    Contact details

    traceIdstring

    Unique trace identifier for this operation