GoHighLevel Contacts API

Create Contact

POST/contacts/

POST /contacts/ This endpoint takes 50 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/
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, prefer `hylo_bulk_upsert_contacts` — it handles create-or-update and runs in parallel server-side.
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`	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`

Response fields

Top-level fields returned on a successful call.

Name	Type	Description
`contact`	`object`	—
`└id`	`string`	Example: `seD4PfOuKoVMLkEZqohJ`
`└dateAdded`	`string`	Example: `2021-08-31T09:59:41.937Z`
`└dateUpdated`	`string`	Example: `2021-08-31T09:59:41.937Z`
`└deleted`	`boolean`	Example: `false`
`└tags`	`array`	Example: `nisi sint commodo amet,consequat`
`└type`	`string`	Example: `read`
`└customFields`	`array`	—
`└locationId`	`string`	Example: `ve9EPM428h8vShlRW1KT`
`└firstName`	`string`	Example: `rubika`
`└firstNameLowerCase`	`string`	Example: `rubika`
`└fullNameLowerCase`	`string`	Example: `rubika deo`
`└lastName`	`string`	Example: `Deo`
`└lastNameLowerCase`	`string`	Example: `deo`
`└email`	`string`	Example: `rubika@deos.com`
`└emailLowerCase`	`string`	Example: `rubika@deos.com`
`└bounceEmail`	`boolean`	Example: `false`
`└unsubscribeEmail`	`boolean`	Example: `false`
`└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`	—
`└phone`	`string`	Example: `+18832327657`
`└address1`	`string`	Example: `3535 1st St N`
`└city`	`string`	Example: `ruDolomitebika`
`└state`	`string`	Example: `AL`
`└country`	`string`	Example: `US`
`└postalCode`	`string`	Example: `35061`

Example request

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

curl -X POST 'https://services.leadconnectorhq.com/contacts/' \
  -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