If you build workflows, emails or webhooks in HighLevel, you need to find custom field keys in GoHighLevel constantly. The key is what turns a field like "Funding Amount Requested" into a merge tag you can drop into an SMS, and one wrong character means a blank where the value should be. This guide shows where the keys live, how to copy them reliably, and how to pull them in bulk when you manage a lot of sub-accounts.
What a custom field key actually is
Every custom field in a sub-account has three identifiers:
| Identifier | Example | Where you use it |
|---|---|---|
| Name (label) | Funding Amount Requested | What users see on the contact record and in forms |
| Field key | contact.funding_amount_requested |
Merge tags, workflow conditions, some integrations |
| Field ID | a random string like kX9... |
API calls that update a contact's custom fields |
The key is generated from the field name when the field is created. Wrap it in double curly braces and you have the merge tag: {{contact.funding_amount_requested}}. Opportunity fields work the same way with an opportunity. prefix.
Two rules from HighLevel's own documentation are worth knowing up front. Merge fields are case-sensitive, so {{contact.name}} works and {{Contact.Name}} does not. And there is no built-in fallback value: if the field is empty, the merge tag renders as a blank. (HighLevel suggests Conditional Send in the email builder as a workaround.)
How to find a custom field key in GoHighLevel
As of October 2026, the native path looks like this:
- Open the sub-account and click Settings in the lower-left menu.
- Click Custom Fields.
- Use the object selector at the top of the page to choose Contact or Opportunity.
- Stay on the Fields tab. The list shows each field's name, type, folder and key.
- Search for the field by name, then copy the key from its row.
- Paste it inside double curly braces wherever you need the merge tag.
If your sub-account has a long list, use the search box rather than scrolling. Fields are grouped into folders, and the folder a field sits in has nothing to do with its key.
Using the merge field picker instead
Inside the email builder, SMS composer and workflow actions there is a merge field (custom variable) picker. It lists standard and custom fields, and clicking one inserts the correct tag. This is the safest option when you are already in the editor, because you can't mistype it.
The picker is less helpful when you are working outside HighLevel, for example writing a webhook body in another tool, building a Zapier step, or writing documentation for a client. That is when you go back to Settings and copy keys one by one.
Pulling keys through the API
If you are comfortable with an API client, you can list every field at once. With a token that has the locations/customFields.readonly scope:
GET https://services.leadconnectorhq.com/locations/{locationId}/customFields?model=contact
Authorization: Bearer <your token>
Version: 2021-07-28
The response includes each field's id, name, fieldKey and dataType. Change model to opportunity for opportunity fields. You can paste the JSON into a converter and drop it into a spreadsheet. See our Private Integration token guide if you need a token for a single sub-account.
Where to use the field ID instead of the key
The key and the ID are not interchangeable. Merge tags and most workflow steps use the key. The Contacts API is different: when you update a contact's custom fields through the API, you send each field's id with its value, not the key. If you're writing a webhook that creates or updates contacts in HighLevel, keep both columns in your build sheet so you don't have to look them up twice.
A simple build sheet with four columns (name, key, ID, type) for every field you touch saves a lot of back-and-forth, especially when someone else picks up the project later.
Common mistakes that break merge tags
Most "my merge tag is blank" tickets come down to one of these:
- Guessing the key from the label. If someone renamed "Loan Amount" to "Funding Amount Requested," the key may still say
loan_amount. Always copy from the list. - Wrong object. A contact merge tag in an opportunity-based action, or the reverse, will come back empty. HighLevel also doesn't let you switch a field's object after creation, so a field built on the wrong object has to be recreated.
- Two fields with similar names. Snapshots and quick builds often leave "Monthly Revenue" and "Monthly Revenue 2" side by side. Check the key, not the name, to confirm which one your form writes to.
- Case changes. Typing the key by hand and capitalizing a letter is enough to break it.
- Custom values vs custom fields. Custom values use a different prefix (
custom_values.). If you aren't sure which one you need, read custom values vs custom fields.
Where the native way gets slow
Finding one key is quick. The pain shows up at agency scale:
- You are building a webhook with 25 fields and copying each key individually from Settings.
- You manage dozens of sub-accounts and need the same key from each, and keys aren't guaranteed to match between them.
- A client asks for a list of every field and its merge tag, and there is no native export of the field list.
- You need custom object fields or custom values in the same list, and they live on different settings pages.
The API solves the export problem, but it means juggling tokens and JSON for every sub-account.
How Field Finder handles it
Field Finder is the read-only tool we built for this, after doing it by hand across our own sub-accounts. You connect your agency once (or one sub-account with a Private Integration token), pick a sub-account, and every custom field shows up in one searchable list with its key, ID and ready-to-paste merge tag.
- Search by name, key, ID, type, folder or even dropdown option text.
- Click a row to copy the merge tag, for contact, opportunity, custom object and custom value tags.
- Filter by object, then export the list to CSV for a client handoff or a webhook build sheet.
- It never writes to the sub-account. It only reads field definitions.
One honest limit: HighLevel's API doesn't expose folder names for contact and opportunity fields, so Field Finder shows those folders by ID. Custom object folders show their names.
If you only touch one sub-account a month, the native Settings page is fine. If you build in several a week, a single searchable list saves real time.
Questions
Where are custom field keys in GoHighLevel?
In the sub-account, go to Settings, then Custom Fields, and pick the object (Contact or Opportunity) at the top. The field list shows each field's key, which you can copy from there.
What does a GoHighLevel merge tag look like?
A merge tag is the field key wrapped in double curly braces, for example {{contact.first_name}} or {{contact.funding_amount_requested}}. Merge tags are case-sensitive, so paste them exactly as GoHighLevel shows them.
Does renaming a custom field change its key?
Don't count on it. The key is generated when the field is created, so after a rename the key can still reflect the old name. Always copy the key from the field list instead of guessing it from the label.
Can I get custom field keys through the API?
Yes. A GET request to the Custom Fields endpoint for a location returns every field with its id, name, fieldKey and data type. You need a token with the custom fields read scope.