HighLevel: Upsert Contact

← Contacts operations · Get started

Operation gohighlevel.upsert_contact

Provider route: POST /contacts/upsert. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["contacts"]["upsertContact"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.contacts.upsertContact(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.contacts.upsert_contact(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Upsert Contact — request body — body

Referenced models: Upsert Contact — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Upsert Contact — response body

Referenced models: Upsert Contact — response body

Schemas

16 more schemas are linked from the tables above, on the schema pages.

Upsert Contact — response body

Field	Type	Presence	Description and constraints
$	object	Root
contact	JSON	Optional	Contact details
contact (allOf 1)	Model	All variants apply	Expand Get Contact — response body — contact address1, assigned To, attachments, attribution Source, business Id, city, company Name, country, custom Fields, date Added, date Of Birth, date Updated, dnd, dnd Settings, email, email Lower Case, first Name, first Name Lower Case, full Name Lower Case, id, keyword, last Activity, last Attribution Source, last Name, last Name Lower Case, location Id, name, phone, postal Code, source, ssn, state, tags, timezone, type, visitor Id, website
new	boolean	Optional	Whether a new contact was created (true) or an existing one was updated (false)
traceId	string	Optional	Unique trace identifier for this operation

Referenced models: Get Contact — response body — contact address1, assigned To, attachments, attribution Source, business Id, city, company Name, country, custom Fields, date Added, date Of Birth, date Updated, dnd, dnd Settings, email, email Lower Case, first Name, first Name Lower Case, full Name Lower Case, id, keyword, last Activity, last Attribution Source, last Name, last Name Lower Case, location Id, name, phone, postal Code, source, ssn, state, tags, timezone, type, visitor Id, website

Upsert Contact — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
address1	JSON	Optional
address1 (anyOf 1)	string	Alternative	Street address of the contact
address1 (anyOf 2)	null	Alternative
assignedTo	string	Optional	User's Id
city	JSON	Optional
city (anyOf 1)	string	Alternative	City of the contact
city (anyOf 2)	null	Alternative
companyName	JSON	Optional
companyName (anyOf 1)	string	Alternative	Company name of the contact
companyName (anyOf 2)	null	Alternative
country	string	Optional	Country code of the contact (ISO 3166-1 alpha-2)
createNewIfDuplicateAllowed	boolean	Optional	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: false
customFields	array	Optional	List of custom field values to assign to the contact
customFields[]	JSON	Each item
customFields[] (anyOf 1)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Text Field
customFields[] (anyOf 2)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Large Text Field
customFields[] (anyOf 3)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Single Select Field
customFields[] (anyOf 4)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Radio Field
customFields[] (anyOf 5)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Numeric Field
customFields[] (anyOf 6)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Monetory Field
customFields[] (anyOf 7)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Checkbox Field
customFields[] (anyOf 8)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — Multi Select Field
customFields[] (anyOf 9)	Model	Alternative	Expand Create Contact — request body — body custom Fields item field Value, field value, id, key — File Field
dateOfBirth	JSON	Optional
dateOfBirth (anyOf 1)	object	Alternative	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
dateOfBirth (anyOf 2)	null	Alternative
dnd	boolean	Optional	Whether Do Not Disturb is enabled for the contact
dndSettings	JSON	Optional	Per-channel DND settings for the contact
dndSettings (allOf 1)	Model	All variants apply	Expand Create Contact — request body — body dnd Settings call, email, fb, gmb, sms, whats App
email	JSON	Optional
email (anyOf 1)	string	Alternative	Email address of the contact
email (anyOf 2)	null	Alternative
firstName	JSON	Optional
firstName (anyOf 1)	string	Alternative	First name of the contact
firstName (anyOf 2)	null	Alternative
gender	string	Optional	Gender of the contact
inboundDndSettings	JSON	Optional	Inbound DND settings per channel for the contact
inboundDndSettings (allOf 1)	Model	All variants apply	Expand Create Contact — request body — body inbound Dnd Settings all
lastName	JSON	Optional
lastName (anyOf 1)	string	Alternative	Last name of the contact
lastName (anyOf 2)	null	Alternative
locationId	string	Required within parent	Location Id the contact should be created under
name	JSON	Optional
name (anyOf 1)	string	Alternative	Full name of the contact
name (anyOf 2)	null	Alternative
phone	JSON	Optional
phone (anyOf 1)	string	Alternative	Phone number of the contact
phone (anyOf 2)	null	Alternative
postalCode	string	Optional	Postal code of the contact
source	string	Optional	Source from which the contact was created
state	JSON	Optional
state (anyOf 1)	string	Alternative	State of the contact
state (anyOf 2)	null	Alternative
tags	array	Optional	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.
tags[]	string	Each item
timezone	JSON	Optional
timezone (anyOf 1)	string	Alternative	Timezone of the contact
timezone (anyOf 2)	null	Alternative
website	JSON	Optional
website (anyOf 1)	string	Alternative	Website URL of the contact
website (anyOf 2)	null	Alternative

Referenced models: Create Contact — request body — body custom Fields item field Value, field value, id, key — Checkbox Field, Create Contact — request body — body dnd Settings call, email, fb, gmb, sms, whats App, Create Contact — request body — body custom Fields item field Value, field value, id, key — File Field, Create Contact — request body — body inbound Dnd Settings all, Create Contact — request body — body custom Fields item field Value, field value, id, key — Large Text Field, Create Contact — request body — body custom Fields item field Value, field value, id, key — Monetory Field, Create Contact — request body — body custom Fields item field Value, field value, id, key — Multi Select Field, Create Contact — request body — body custom Fields item field Value, field value, id, key — Numeric Field, Create Contact — request body — body custom Fields item field Value, field value, id, key — Radio Field, Create Contact — request body — body custom Fields item field Value, field value, id, key — Single Select Field, Create Contact — request body — body custom Fields item field Value, field value, id, key — Text Field

Create Contact — request body — body custom Fields item field Value, field value, id, key — Checkbox Field

Field	Type	Presence	Description and constraints
$	object	Root
fieldValue	array	Optional	Array of selected checkbox values for the custom field (preferred).
fieldValue[]	string	Each item
field_value	array	Optional	Deprecated. Use `fieldValue` instead.
field_value[]	string	Each item
id	string	Required within parent	Pass either `id` or `key` of custom field
key	string	Optional	Pass either `id` or `key` of custom field

Get Contacts By Business Id — response body — contacts item custom Fields item

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Optional	Unique identifier of the custom field
value	string	Optional	Value of the custom field

Policy, approvals and errors

SDK function policy ID: gohighlevel.upsert_contact. Catalog operation: upsert-contact. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["contacts.write"]

Pinned headers: {"Version": "v3"}

Official provider source