Skip to main content
GHL MCP Guide
CFD

Contact Fields

Contacts & CRM · Intermediate · Updated March 2026

Manage custom data fields on contacts for storing business-specific information. Read and write custom field values across any contact record.

Every business has data that doesn’t fit into standard CRM fields. A roofing company needs roof age and material type. A med spa needs treatment history and skin type. A real estate agent needs property preferences and pre-approval status. Custom fields store this business-specific data on contact records, and managing them through MCP lets you automate data collection from external sources.

What This MCP Tool Does

This tool handles reading and writing custom field values on contact records. When you create or update a contact through Contact CRUD, you can include custom field values. This tool focuses on the field-level operations — understanding what fields exist, what types they are, and how to correctly set values on contacts.

Custom fields are defined at the location level using Location Custom Fields, then populated per contact through this tool’s integration with the contact endpoints.

How Custom Fields Work with Contacts

Custom field values are set through the contact create and update endpoints. When sending custom field data, you use the field’s unique ID (not its display name) paired with the value:

customFields: [
  { "id": "field_abc123", "value": "Premium" },
  { "id": "field_def456", "value": "2024-06-15" }
]

To read custom field values, retrieve the contact via Contact CRUD. The response includes all custom field values associated with the contact.

Authentication

Requires a Private Integration Token (PIT) with the contacts scope enabled. Field definitions are managed through the locations scope.

Field Types

GHL supports several custom field types:

  • Text — single-line text input
  • Textarea — multi-line text
  • Number — numeric values
  • Date — date values in ISO format
  • Dropdown — single selection from predefined options
  • Multi-select — multiple selections from predefined options
  • Checkbox — boolean true/false
  • File upload — file attachments (handled differently via API)

Each field type has its own validation rules. Sending a text value to a number field, or an invalid option to a dropdown, will result in an error.

Important Notes

The most common mistake is using the field name instead of the field ID. Custom field IDs are alphanumeric strings generated by GHL when the field is created. You must first retrieve the field definitions from Location Custom Fields to get the correct IDs.

Dropdown and multi-select fields require values that exactly match the predefined options. If the options are “Gold,” “Silver,” “Bronze” and you send “gold” (lowercase), it may not match. Check the field definition for exact option values.

Custom fields are scoped to a location. Each sub-account can have its own set of custom fields with different IDs, even if the field names look the same. Never hardcode field IDs across locations.

Common Questions

How do I find the ID of a custom field? Use Location Custom Fields to list all field definitions for the location. Each definition includes the field ID, name, type, and options.

Can I create custom fields through MCP? Yes, but through the Location Custom Fields tool, not through the contact endpoints. Contact endpoints only read and write values on existing fields.

What happens if I send a value for a field ID that doesn’t exist? The value is silently ignored. No error is thrown, but the data isn’t stored. Always validate field IDs before sending data.

Can I clear a custom field value? Yes. Send an empty string or null as the value for the field ID in an update request.

Back to GHL MCP Guide