GoHighLevel Custom Fields: Setup Guide (2026)

By Dr Priya Jaganathan, GoHighLevel Certified Admin · HL Growth Partner, Australia · Updated 3 September 2026 · 8 min read

GoHighLevel custom fields are where most sub-accounts quietly fall apart. The first few are created in a hurry to get a form live, the next dozen appear when a workflow needs somewhere to write a value, and within six months nobody can tell you what "Field 3 copy" holds or whether anything still reads it. I have audited hundreds of Australian sub-accounts and the pattern is the same every time: the data model was never designed, it accreted.

This guide covers the full setup properly. Where custom fields live, which of the twelve field types to pick and when, a naming convention that survives handover, how to reference fields in workflows and merge tags, how they behave inside snapshots and webhook payloads, and how to govern them so the account is still tidy in year three. The examples are Australian because that is who I build for: ABNs, NDIS numbers, states and service addresses.

Where GoHighLevel custom fields live and what they attach to

In a sub-account, go to Settings → Custom Fields. This is the single registry for every field in the location, regardless of where the field is later used. Forms, surveys, workflows, the contact record and the opportunity card all read from this one list, so anything you create here is immediately available everywhere.

Contact fields versus opportunity fields

When you add a field you choose the object it belongs to. Contact fields describe the person or business: ABN, state, preferred contact time. Opportunity fields describe a specific deal: quoted amount, site inspection date, the address of the job being priced. The distinction matters because a contact can have several opportunities over time. If you store the quoted amount on the contact, the second quote overwrites the first. Store it on the opportunity and each deal keeps its own value. My rule: if the value would be different for two deals with the same person, it belongs on the opportunity.

Custom Objects are a separate thing

Custom Objects let you model records that are neither a contact nor an opportunity, such as properties, vehicles or policies, each with its own fields and associations. They are powerful, but they are a different feature with their own settings area. This article is about fields on the standard contact and opportunity objects. If you find yourself creating "Vehicle 1 Rego", "Vehicle 2 Rego" and "Vehicle 3 Rego" as contact fields, that is the signal you need an object instead.

Every field type and when each one is right

HighLevel gives you twelve field types. Choosing the right one up front matters because changing a type later usually means creating a new field and migrating data. The table below is the reference I hand to every client admin.

The choices that cause the most rework

Two mistakes dominate. The first is using a single line field for something that should be a dropdown. If "State" is free text you will end up with "NSW", "nsw", "New South Wales" and "N.S.W." and every workflow condition has to catch all four. A dropdown with eight options removes the problem permanently. The second is storing dates as text. A date typed into a single line field cannot trigger a renewal reminder ninety days before it falls due; a proper Date field can. HighLevel sets limits on the number of fields and options per location; check the current help article before designing anything unusually large.

Folders, naming conventions and unique keys

Custom Fields can be grouped into folders, and you should use them from day one. I typically run four: Business Details, Service Details, Internal, and Calculated. Folders also control how the fields display on the contact record, so a sensible grouping makes the sales team's life easier as well as the admin's.

A prefix convention that survives handover

Folders help humans; prefixes help everything else. In dropdowns inside the workflow builder, fields appear as a flat alphabetical list, and a prefix tells you what a field is for without opening it. The scheme I use across every snapshot:

• FORM_ for values captured directly from a form or survey, such as FORM_Service_Address or FORM_Preferred_Contact_Time. Humans typed these, so treat them with mild suspicion.
• INT_ for internal fields the client never sees, such as INT_Account_Manager or INT_Onboarding_Stage.
• CALC_ for values written by a workflow rather than a person, such as CALC_Lead_Score or CALC_Days_To_Renewal. If a CALC_ field is wrong, you look at the workflow, not the contact.
• API_ for values pushed in from an external system via webhook or integration, so nobody edits them by hand.

Unique keys and merge syntax

Every field has a display name and a unique key. The key is generated from the name at creation and is what everything technical uses. Renaming the display name later does not change the key, which is both a blessing and a trap. To merge a field into an email, SMS or internal notification you use {{contact.custom_field_key}}, for example {{contact.form_service_address}}. Opportunity fields use {{opportunity.custom_field_key}}. Because the key is fixed, get the name right the first time; a field called "test 2" that is later renamed to "ABN" will carry the key test_2 forever, and every merge tag and webhook payload will show it.

Mapping form and survey questions to fields

The form builder lets you drop in standard fields and custom fields from the same picker. Every question that should persist on the contact record must be mapped to a custom field; an unmapped custom question is stored on the submission only and cannot be used in a workflow condition or merge tag. A common failure is a form built with "Custom Text" elements that look like fields but write nowhere.

Surveys follow the same rule with one extra consideration: conditional logic in surveys is far cleaner when each branch writes to a dropdown or radio field, because the downstream workflow can then branch on a fixed set of values. For a typical AU trades enquiry form I map: FORM_State (dropdown), FORM_Service_Address (single line), FORM_Preferred_Contact_Time (dropdown with Morning, Afternoon, Evening), FORM_ABN (single line, for commercial enquiries), and FORM_Site_Photos (file upload). For an NDIS provider the intake survey writes FORM_NDIS_Number, FORM_Plan_Managed (radio: Self, Plan Managed, NDIA Managed) and FORM_Plan_End_Date (date).

Using custom fields in workflows, pipelines and smart lists

This is where field type discipline pays off. The workflow builder interacts with fields in four ways.

Update Contact Field action

This action writes a value into any contact field. It is how every CALC_ field gets populated: a workflow tallies engagement and writes CALC_Lead_Score, or copies a value from an opportunity into a contact field so it can be merged into an email. You can write a fixed value or a merge tag from elsewhere in the workflow, including values from an inbound webhook.

If/Else conditions on field values

Conditions read fields and branch. The available operators depend on the type: dropdowns give you "is" and "is not", numbers and monetary fields add greater-than and less-than, dates give you before and after, checkboxes give you true or false. If you want a deeper walkthrough of building branches, my guide to workflow If/Else conditions covers the operators for every type. A practical example: If FORM_State is WA or NT, route to the western team calendar; else route to the eastern team.

Wait until a field has a value

The Wait step can pause until a condition on a field is met. This is the right pattern for "wait until INT_Quote_Sent_Date is set, then start the follow-up sequence" rather than guessing a fixed delay. Pair it with a timeout branch so contacts do not sit in the wait forever.

Triggering on field changes

The Contact Changed trigger, with a filter on a specific custom field, fires whenever that field is updated. It is the cleanest way to launch a renewal sequence when FORM_Plan_End_Date is entered, or to notify an account manager when API_Account_Status flips to Overdue. Keep these triggers narrow; a Contact Changed trigger with no field filter fires on every edit and will flood your workflow history.

Pipelines and smart lists

Opportunity fields show on the opportunity card and can be edited directly from the pipeline view, which is why quoted values and inspection dates belong there. See the pipelines and opportunities guide for the layout side. On the contact side, custom fields are filterable in the Contacts view, so a saved filter such as "FORM_State is QLD and CALC_Lead_Score greater than 50" becomes a reusable segment. The smart lists and segments article shows how to turn those filters into lists a team actually uses.

Custom fields versus tags: the decision rule

The question I get asked most is whether something should be a field or a tag. The rule is simple. A tag answers a yes-or-no question about membership: attended the webinar, is a past client, came from the Meta campaign. A field holds a value that has meaning on its own: which state, what ABN, what date. If you find yourself creating tags like "state-nsw", "state-vic" and "state-qld", that is a dropdown field pretending to be a tag, and it will be harder to report on and impossible to merge into a message. Conversely, a checkbox field called "Attended Webinar" is a tag pretending to be a field. A coherent tag strategy and a coherent field architecture are two halves of the same data model.

Snapshots, API and webhook considerations

How fields travel with snapshots

Custom fields, their folders and their options are included when you build a snapshot, and they are created in the destination sub-account on load. This is why the naming convention has to be decided before the first snapshot is cut. When you later push a snapshot update, HighLevel matches fields by key; if someone in the destination account has already created a field with the same key, the update reuses it, and if the key differs the update creates a duplicate. Keys must match across sub-accounts or your workflows will reference one field in the agency template and a different one in the client account. The GoHighLevel snapshots guide covers the load and update behaviour in detail.

API and webhook payloads

When a workflow sends an outbound webhook, custom fields are included in the payload keyed by their unique key, so the receiving system sees form_service_address rather than "Service Address". Inbound, the API and inbound webhook triggers can write to custom fields, but you must reference the field by key or ID, not by display name. If you rename a field's label the integration keeps working; if you delete and recreate it the ID changes and the integration breaks silently. Anything wired through GoHighLevel webhooks should be documented against field keys, and the official HighLevel custom fields help article lists the current type identifiers used in the API.

Governance: stopping field sprawl

Field sprawl is the slow accumulation of fields nobody owns. It makes the contact record unreadable, slows down every workflow dropdown, and eventually causes a real error when someone picks the wrong "Address" field out of five. Three practices keep it under control.

One owner, one register

Keep a simple register outside the platform: field name, key, type, folder, what writes to it, what reads it, and who asked for it. Any new field goes through one person who checks whether an existing field already covers the need. In an agency, that person is the snapshot owner, because every ad hoc field in a client account is a future snapshot conflict.

Deprecating rather than deleting

Deleting a field removes its data on every contact and breaks every workflow, form and merge tag that references it, without warning. Instead, rename it with a ZZ_DEPRECATED_ prefix and move it to a Deprecated folder. It sinks to the bottom of every list, stays out of the way, and the data survives. After a full quarter with no references, delete it.

Quarterly audit

Once a quarter, export the field list and walk it. For each field ask: does anything write to it, does anything read it, and does it hold a value on more than a handful of contacts? Fields failing all three are deprecated. Fields with inconsistent values are candidates for conversion to a dropdown. This takes an hour and saves days of debugging later. If you are managing multiple locations on an agency plan, the audit runs on the snapshot master first and cascades outward; the GoHighLevel pricing page sets out which plans include unlimited sub-accounts for that model.

Common mistakes to avoid

• Using single line text for anything with a fixed set of answers, especially state, lead source and service type.
• Storing deal-specific values such as quote amount on the contact instead of the opportunity, so each new deal overwrites the last.
• Naming a field carelessly at creation, then renaming it, leaving a meaningless unique key baked into every merge tag and webhook.
• Building form questions that are not mapped to a custom field, so the answers never reach the contact record.
• Deleting fields instead of deprecating them, wiping data and silently breaking workflows.
• Creating fields directly inside client sub-accounts instead of in the snapshot master, causing key mismatches on the next update.

If you want a clean custom-field architecture and naming standard built into your snapshot so every sub-account starts tidy, book a strategy call with the HL Growth Partner team.

Book Your Strategy Call →

Frequently asked questions

Where do I create GoHighLevel custom fields?

In the sub-account, go to Settings and then Custom Fields. Choose whether the field belongs to the contact or the opportunity object, pick the type, assign a folder and save. The field is then available in forms, surveys, workflows, the contact record and the pipeline view.

Can I change a custom field's type after creating it?

In most cases no. If you need a different type, create a new field with the correct type, migrate the data with a workflow or CSV import, update every reference, then deprecate the old field. This is why choosing dropdown over free text at the start saves so much time.

What is the merge tag for a custom field?

Use two curly braces with contact, a dot, and the field's unique key, for example the ABN field with key form_abn is merged as {{contact.form_abn}}. Opportunity fields use the opportunity prefix instead. The key is shown in the field's settings.

Do custom fields come across in a snapshot?

Yes. Fields, folders and dropdown options are included in a snapshot and created in the destination account on load. Snapshot updates match fields by key, so keep keys identical across sub-accounts and always add new fields in the snapshot master rather than in individual client accounts.

Should I use a custom field or a tag?

Use a tag for yes-or-no membership such as attended an event or is a past client. Use a field when the data has a value of its own such as a state, a date, an amount or an identifier like an NDIS number. If you are creating several tags that differ only by value, you need a dropdown field.

Related articles

• GoHighLevel tags vs custom fields
• GoHighLevel custom values
• GoHighLevel custom objects
• GoHighLevel forms and surveys