Field Folders Setup

Organize your custom fields into folder hierarchies for cleaner management in both the API and the GHL UI. This guide covers creating, updating, and deleting field folders.

Prerequisites

Before creating field folders, confirm you have:

• A GoHighLevel sub-account with custom fields enabled
• At least one custom field already created (see Custom Fields V2)
• Your locationId from Settings > Business Profile
• A Private Integration Token (PIT) with the custom-fields scope
• A REST client such as Postman, Insomnia, or curl

Set Up Authentication

Field folder endpoints use the same custom-fields scope as the Custom Fields V2 API.

If you already have a PIT with this scope, reuse it. Otherwise:

1. Go to Settings > Integrations > Private Integrations
2. Create or edit an integration and enable the custom-fields scope
3. Copy the token and store it securely

export GHL_TOKEN="your-private-integration-token"
export LOCATION_ID="your-location-id"

Base URL: https://services.leadconnectorhq.com. Include these headers:

Authorization: Bearer $GHL_TOKEN
Content-Type: application/json
Version: 2021-07-28

Make Your First Call

Create a folder by sending a POST to /custom-fields/folders:

curl -X POST "https://services.leadconnectorhq.com/custom-fields/folders" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "locationId": "'"$LOCATION_ID"'",
    "name": "Property Details",
    "objectKey": "contact"
  }'

The name is the display label shown in the GHL interface. The objectKey scopes the folder to a specific object type, matching the same keys used in Custom Fields V2. All fields assigned to this folder must belong to the same object.

Once the folder exists, assign fields to it by including the folderId when creating or updating custom fields via POST /custom-fields or PUT /custom-fields/{fieldId}.

Update a folder with PUT /custom-fields/folders/{folderId} to rename it. Delete a folder with DELETE /custom-fields/folders/{folderId} to remove the grouping. Deleting a folder does not delete the fields inside it. Those fields revert to being ungrouped.

Handle the Response

A successful POST /custom-fields/folders returns the new folder:

{
  "folder": {
    "id": "fld_abc123",
    "locationId": "your-location-id",
    "name": "Property Details",
    "objectKey": "contact",
    "createdAt": "2026-03-07T12:00:00Z"
  }
}

Save the folder.id for use when assigning fields and for update or delete operations. When you list fields with GET /custom-fields/object/{objectKey}, each field includes its folderId so you can reconstruct the folder structure programmatically.

Common errors: 400 means the name or objectKey is missing. 401 indicates an invalid token or missing custom-fields scope. 404 on update or delete means the folder ID does not exist. 409 means a folder with that name already exists on the target object.

Test Your Setup

Walk through these steps to confirm folder management works:

1. Create a folder with POST /custom-fields/folders and note the returned id
2. Create a custom field with POST /custom-fields, passing the folder’s id as folderId
3. List fields with GET /custom-fields/object/{objectKey} and verify the field shows the correct folderId
4. Rename the folder with PUT /custom-fields/folders/{folderId}
5. Delete the folder with DELETE /custom-fields/folders/{folderId} and confirm the field still exists but is now ungrouped

If fields do not appear grouped in the GHL UI after assignment, refresh the page and verify the objectKey on the folder matches the field’s object scope.

Next Steps

Read the full Field Folders guide for best practices on folder naming conventions and organizational strategies. Explore Custom Fields V2 for advanced field type configuration, or set up Object Schema CRUD to define custom objects with fields built into the schema from the start.