GoHighLevel Contacts API

Upsert Contact

POST/contacts/upsert

POST /contacts/upsert 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 It takes 51 body fields, requires the contacts.write scope and authenticates with a sub-account (location) token.

Request and authentication

Method: POST
Full URL: https://services.leadconnectorhq.com/contacts/upsert
Scopes: contacts.write
Token type: Sub-account (location) token
Accepted auth: OAuth Access Token, Private Integration Token
API version header: Version: 2021-07-28
Schema verified: 22 June 2026

Notes from the field

For multi-contact imports, use the `hylo_bulk_upsert_contacts` MCP tool — one call instead of N round-trips.
Pass `tags` inline here to skip a follow-up add-tags call (saves 1 round-trip per contact).
Pass `customFields` inline here to skip per-field update-contact-field calls.

This endpoint is safe to fan out in parallel, so a batch of records costs roughly one round trip instead of one per record. Hylo's bulk tools do that server-side and retry HighLevel's 429s with back-off.

Request body

JSON body fields. Nested objects are shown indented under their parent.

Name	Type	Description
`firstName`	`string`	Example: `Rosan`
`lastName`	`string`	Example: `Deo`
`name`	`string`	Example: `Rosan Deo`
`email`	`string`	Example: `rosan@deos.com`
`locationId`required	`string`	Example: `ve9EPM428h8vShlRW1KT`
`gender`	`string`	Example: `male`
`phone`	`string`	Example: `+1 888-888-8888`
`address1`	`string`	Example: `3535 1st St N`
`city`	`string`	Example: `Dolomite`
`state`	`string`	Example: `AL`
`postalCode`	`string`	Example: `35061`
`website`	`string`	Example: `https://www.tesla.com`
`timezone`	`string`	Example: `America/Chihuahua`
`dnd`	`boolean`	Example: `true`
`dndSettings`	`object`	—
`└Call`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└Email`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└SMS`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└WhatsApp`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└GMB`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└FB`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`inboundDndSettings`	`object`	—
`└all`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`
`└message`	`string`	—
`tags`	`array`	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. Example: `nisi sint commodo amet,consequat`
`customFields`	`array`	—
`source`	`string`	Example: `public api`
`dateOfBirth`	`object`	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 Example: `1990-09-25`
`country`	`string`	Example: `US`
`companyName`	`string`	Example: `DGS VolMAX`
`assignedTo`	`string`	User's Id Example: `y0BeYjuRIlDwsDcOHOJo`
`createNewIfDuplicateAllowed`	`boolean`	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. Example: `false`

Response fields

Top-level fields returned on a successful call.

Name	Type	Description
`new`	`boolean`	Example: `true`
`contact`	`object`	—
`└id`	`string`	Example: `seD4PfOuKoVMLkEZqohJ`
`└name`	`string`	Example: `rubika deo`
`└locationId`	`string`	Example: `ve9EPM428h8vShlRW1KT`
`└firstName`	`string`	Example: `rubika`
`└lastName`	`string`	Example: `Deo`
`└email`	`string`	Example: `rubika@deos.com`
`└emailLowerCase`	`string`	Example: `rubika@deos.com`
`└timezone`	`string`	Example: `Asia/Calcutta`
`└companyName`	`string`	Example: `DGS VolMAX`
`└phone`	`string`	Example: `+18832327657`
`└dnd`	`boolean`	Example: `true`
`└dndSettings`	`object`	—
`└Call`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└Email`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└SMS`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└WhatsApp`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└GMB`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└FB`	`object`	—
`└status`required	`string`	One of: `active`, `inactive`, `permanent`
`└message`	`string`	—
`└code`	`string`	—
`└type`	`string`	Example: `read`
`└source`	`string`	Example: `public api`
`└assignedTo`	`string`	Example: `ve9EPM428h8vShlRW1KT`
`└address1`	`string`	Example: `3535 1st St N`
`└city`	`string`	Example: `ruDolomitebika`
`└state`	`string`	Example: `AL`
`└country`	`string`	Example: `US`
`└postalCode`	`string`	Example: `35061`
`└website`	`string`	Example: `https://www.tesla.com`
`└tags`	`array`	Example: `nisi sint commodo amet,consequat`
`└dateOfBirth`	`string`	Example: `Date format YYYY-MM-DD`
`└dateAdded`	`string`	Example: `2021-07-02T05:18:26.704Z`
`└dateUpdated`	`string`	Example: `2021-07-02T05:18:26.704Z`
`traceId`	`string`	—

Example request

Copy-paste ready. Swap YOUR_TOKEN for your access token or Private Integration Token.

curl -X POST 'https://services.leadconnectorhq.com/contacts/upsert' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
    "locationId": "ve9EPM428h8vShlRW1KT"
  }'

Skip the schema lookup

Hylo gives your AI agent this schema — and the other 52 documented here — without you looking anything up. Ask in plain English; it picks the endpoint, fills the body, and can run the call against your own sub-account.

View pricing Read the setup guide

More contacts endpoints