> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Upsert contact

> Creates or updates a contact using HighLevel's duplicate-contact policy.

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

```ts automations/highlevel-upsert-contact.automation.ts theme={null}
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.