Upsert Contact
highlevel.upsert_contact
ActionCRM & salesconnection required
Calls the HighLevel API with the connection's credentials.
Create a contact, or update the one that already holds this email address or phone number.
Connection
- Required
- Yes — the node will not save without one
- Auth type
- OAuth 2.0
- Providers
- HighLevel
- Secret shape
- {"client_id": "…", "client_secret": "…", "refresh_token": "…"} for a marketplace app, or {"access_token": "…"} for a Private Integration Token
- Config it needs
- location_id, user_type, base_url
- Resolved by
- config.connection_id, else node.connection_id
Configuration
22 fields, none required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.
| Field | Type | Required | Default | Constraints | Example |
|---|---|---|---|---|---|
first_name Stored on the contact in HighLevel; blank leaves it unset. | string | No | — | — | — |
last_name Stored on the contact in HighLevel; blank leaves it unset. | string | No | — | — | — |
name Full name, when you do not have the parts. | string | No | — | — | — |
email Email address. | string | No | — | email format | — |
phone Phone number in E.164, e.g. +15558675309. | string | No | — | — | — |
address1 Street address. | string | No | — | — | — |
city Stored on the contact in HighLevel; blank leaves it unset. | string | No | — | — | — |
state State or region. | string | No | — | — | — |
postal_code Postal or ZIP code. | string | No | — | — | — |
country Two-letter country code, e.g. US. | string | No | — | — | — |
website Absolute http(s) URL to store; blank leaves it unset. | string | No | — | — | — |
timezone IANA timezone, e.g. America/Chicago. | string | No | — | — | — |
source Where the contact came from. | string | No | — | — | — |
assigned_to User id the contact is assigned to. | string | No | — | — | — |
date_of_birth Date of birth, YYYY-MM-DD. | string | No | — | matches \d{4}-\d{2}-\d{2} | 2026-01-31 |
dnd Mark the contact Do-Not-Disturb across every channel. | boolean | No | — | — | — |
custom_fields HighLevel's customFields list, as JSON — one entry per field, each with the field's id (or key) and its value. | array | No | — | array of object | — |
tags Tags to set on the contact, as a list, a JSON array or a comma-separated string. | array | No | — | array of string | — |
fields Any other contact body field HighLevel accepts, as JSON. Merged last, so it wins over the fields above. | object | No | — | — | — |
company_name Company the contact belongs to. | string | No | — | — | — |
gender Gender, as HighLevel records it. | string | No | — | — | — |
location_id Sub-account (location) id to act on instead of the connection's own. | string | No | — | — | — |
- At least one of email, phone must be set.
Example configuration
Every value below is the contract’s own example or default — nothing invented.
{
"date_of_birth": "2026-01-31"
}Output
One shape.
result
| Field | Type | Example |
|---|---|---|
contact The contact HighLevel created or matched. | object | — |
new True when a contact was created rather than matched. | boolean | — |
id The contact id, created or matched. | string | — |
{
"contact": {},
"id": "",
"new": false
}Notes
- Scoped to the connection's location_id (the sub-account) unless the node overrides it.
- HighLevel matches on email or phone, so one of the two has to be set or the upsert can only ever create.
See Upsert Contact run in a workflow.
In a technical demo we add the HighLevel connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.