Skip to main content
GHL MCP Guide
CF2

Custom Fields V2

Custom Objects & Schema · Advanced · Updated March 2026

Advanced custom field management with enhanced types, object-key scoping, and folder organization via the V2 API.

Custom Fields V2 is the enhanced field management API that supports advanced field types, scoping by object key, and folder-based organization. This supersedes the basic custom field management available through location endpoints, offering richer configuration options.

What This MCP Tool Does

Full CRUD on custom field definitions with advanced capabilities. Create fields with enhanced types and validation, retrieve fields scoped to specific object types, update field configurations, and delete fields no longer needed. This API version supports both contact-level fields and fields on custom objects.

Endpoint Reference

Create a custom field: POST /custom-fields Define a new field with type, label, validation, and object scope.

Get a field by ID: GET /custom-fields/{fieldId} Retrieve the full field definition.

Update a field: PUT /custom-fields/{fieldId} Modify field properties, validation rules, or display settings.

Delete a field: DELETE /custom-fields/{fieldId} Remove a custom field definition.

Get fields by object key: GET /custom-fields/object/{objectKey} Retrieve all custom fields scoped to a specific object type.

Authentication

Requires a Private Integration Token (PIT) with the appropriate scope enabled.

Key Parameters

When creating or updating fields:

  • name — field label
  • key — unique field identifier
  • type — field type (text, number, date, dropdown, multi-select, boolean, etc.)
  • objectKey — which object type this field belongs to (contact, custom object, etc.)
  • required — whether the field is mandatory
  • validation — rules for acceptable values
  • folderId — optional folder for organization (see Field Folders)

Important Notes

The V2 API unifies field management across contacts and custom objects. The same endpoint handles fields regardless of which object they belong to, using the objectKey parameter to scope them.

Deleting a field definition does not automatically remove the data stored in that field across existing records. Data may become orphaned. Consider clearing field values before deleting the definition.

The objectKey scoping means you can query all fields for a specific object type in a single call. This is essential for building dynamic forms, import mappers, and integration configurations.

For agencies deploying standardized CRM configurations across client sub-accounts, field definitions should be part of your provisioning automation. Create the same field structure in every new location to maintain consistency.

Common Questions

What is the difference between V1 and V2 custom fields? V2 provides a unified API across object types, enhanced field types, folder organization, and richer configuration options. V1 (through location endpoints) is limited to contact-level fields with basic types.

Can I use V2 fields on custom objects? Yes. The V2 API is the primary field management tool for custom objects. Use the objectKey parameter to scope fields to any object type.

How do I migrate from V1 to V2 field management? V2 is additive. Fields created through V1 (location endpoints) are accessible through V2 using the contact object key. You do not need to migrate; V2 reads existing fields.

Back to GHL MCP Guide