Upsert contact - Automate.ax

highlevel.upsertContact creates or updates a contact using HighLevel’s duplicate-contact policy.

automations/highlevel-upsert-contact.automation.ts

import { automation, markSignificant } from "automate.ax"
import { highlevel } from "automate.ax/highlevel"

export default automation("Upsert contact", () => {
  markSignificant(highlevel.upsertContact({}))
})

Input

Field	Type	Required	Description
`firstName`	`string \| null`	No	HighLevel first name value.
`lastName`	`string \| null`	No	HighLevel last name value.
`name`	`string \| null`	No	HighLevel name value.
`email`	`string \| null`	No	HighLevel email value.
`gender`	`string`	No	HighLevel gender value.
`phone`	`string \| null`	No	HighLevel phone value.
`address1`	`string \| null`	No	HighLevel address1 value.
`city`	`string \| null`	No	HighLevel city value.
`state`	`string \| null`	No	HighLevel state value.
`postalCode`	`string`	No	HighLevel postal code value.
`website`	`string \| null`	No	HighLevel website value.
`timezone`	`string \| null`	No	HighLevel timezone value.
`dnd`	`boolean`	No	HighLevel Do Not Disturb setting.
`dndSettings`	`object`	No	HighLevel Do Not Disturb settings.
`inboundDndSettings`	`object`	No	HighLevel inbound Do Not Disturb settings.
`tags`	`string[]`	No	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.
`customFields`	`object[]`	No	HighLevel custom fields value.
`source`	`string`	No	HighLevel source value.
`dateOfBirth`	`string \| null`	No	Birth date in a HighLevel-supported date format such as `YYYY-MM-DD`.
`country`	`string`	No	HighLevel country value.
`companyName`	`string \| null`	No	HighLevel company name value.
`assignedTo`	`string`	No	User’s Id
`createNewIfDuplicateAllowed`	`boolean`	No	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.

Automate.ax supplies the connected sub-account’s location ID. Optional second argument { account } selects a named HighLevel binding.

Output

Field	Type	Required	Description
`new`	`boolean`	No	HighLevel new value.
`contact`	`object`	No	HighLevel contact value.
`traceId`	`string`	No	HighLevel trace id value.

This action calls POST /contacts/upsert with HighLevel API version 2021-07-28 and requires contacts.write. HighLevel validation and permission errors fail the action. Rate limits honor the provider’s retry timing. Automate.ax does not automatically replay this create or send operation after an indeterminate transport failure.