Contacts and opportunities cover most of what an agency tracks, but not everything fits. A dealer tracks vehicles, a property manager tracks units, an equipment lender tracks machines, and each one has its own details. That's what GoHighLevel custom objects are for, and custom object fields work a little differently from the contact fields you know. This guide covers setup, keys and the limits worth knowing before you build.
What a custom object is
A custom object is a new record type in a sub-account, alongside contacts, opportunities and companies. Each object has its own fields and can be associated with contacts and other records. A "Vehicle" object might have VIN, Make, Model and Mileage, and a contact can be linked to the vehicles they own.
Custom object records can be used in smart lists, filters and automations through associations, according to HighLevel's help center.
Native limits worth knowing
As of October 2026, HighLevel's documentation lists:
| Limit | Value |
|---|---|
| Custom objects per sub-account | Up to 10 |
| Unique fields per object | Up to 10 |
| Plans | Available on all plans |
| Who can create or edit objects | Sub-account admins; other users get read-only access |
| Association labels between two objects | Up to 10 |
| Editable after creation | Internal name and primary field can't be changed |
The last row matters most. Plan the object's internal name before you click create, because it becomes part of every key.
How to set up GoHighLevel custom objects fields
Create the object
- In the sub-account, go to Settings, then Objects.
- Click Add Custom Object.
- Enter a singular and plural name, such as Vehicle and Vehicles.
- Review the internal name. You can change it during creation by clicking the code (
</>) icon. After that, it's fixed. - Label the primary display field, the one that identifies each record (for example, VIN or Unit Number).
- Pick an icon, add a description and click Create Custom Object.
Add fields to the object
Open the object from the Objects page and add fields much as you would for contacts: name, type and folder. Common types such as single line, multi line, number, dropdown and date are available. The primary display field and any unique fields (single line text, multi line text, number or phone) identify records, so pick something that really is unique.
Associate it with contacts
Set up associations between the object and contacts (one-to-many or many-to-many), with a label like "Owner Of." This is what lets workflows and smart lists reach object data from a contact.
Finding custom object field keys
Custom object keys follow the pattern custom_objects.<object>.<field>, for example custom_objects.equipment.type. To find one natively, open the object's field list in Settings and copy the key from there. Like contact fields, don't guess the key from the label; copy it.
Through the API, a token with the objects/schema.readonly scope can read object schemas and their fields. Fields on custom objects are created through HighLevel's newer custom fields endpoint, which takes an objectKey (like custom_objects.equipment) and a fieldKey, rather than the location endpoint used for contact fields. Our field key guide covers contact and opportunity keys.
Merge tag caveats
This is where custom objects still trip agencies up. A request on HighLevel's ideas board from April 2026 asks for custom object fields to work fully as merge tags in emails, SMS and documents. Comments there describe partial support in emails and gaps elsewhere. As of October 2026:
- Test any email or SMS that uses a custom object merge tag before turning on the workflow.
- For SMS and documents, consider copying the value onto a contact field with a workflow step and using the contact merge tag instead.
- Keep a list of which object fields are actually used in messages.
An example build: equipment lending
Say an equipment finance broker wants to track the machines on each deal. A clean setup looks like this:
| Item | Setting |
|---|---|
| Object | Equipment / Equipment |
| Internal name | equipment |
| Primary display field | Serial Number |
| Other fields | Type (dropdown), Make, Model, Year (number), Price (number), Vendor |
| Association | Contact "Owner Of" Equipment, one-to-many |
The merge tag for the type field would then follow the custom_objects.equipment.type pattern. A workflow can filter for contacts with associated equipment of a given type, and the deal stays on the opportunity, where pipeline reporting already works.
Planning tips
- Use custom objects for things, not people. People are contacts. Their vehicles, properties or policies are objects.
- Pick a real unique field. VIN, policy number or unit number, not a name.
- Mind the 10-object limit. Don't create one object per minor variation. A "Vehicle" with a Type field beats separate Car, Truck and Van objects.
- Document keys at build time. Anyone writing workflows later will need them.
Where the native way gets slow
Custom object fields live on their own pages, separate from contact and opportunity fields. To see every field in a sub-account, you visit Custom Fields, switch objects, then open each custom object in turn. Comparing objects across sub-accounts built from the same snapshot means doing that twice.
How Field Finder handles it
Field Finder's custom object fields view lists the fields for every custom object in a sub-account, not just contacts and opportunities, in the same searchable list as everything else. Each row has the key, ID and a ready-to-copy merge tag, and custom object folders show their real names.
Search across contact, opportunity and object fields at once, filter by object, and export to CSV. Field Finder is read-only, so it never changes the objects you've built. For comparing two sub-accounts' field lists, see sub-account compare.
Questions
How many custom objects can I create in GoHighLevel?
HighLevel's help center says up to 10 custom objects per sub-account, each with up to 10 unique fields. Custom objects are available on all plans, and only sub-account admins can create or edit them.
What does a custom object field key look like?
Custom object keys use the custom_objects prefix plus the object's internal name, for example custom_objects.equipment, and fields sit under that, like custom_objects.equipment.type. Copy keys from the object's field list rather than typing them.
Can I use custom object fields as merge tags in emails and SMS?
Support is partial as of October 2026. HighLevel's ideas board has an active request for full merge tag support in emails, SMS and documents, so test any message before relying on it.