Contact Fields Setup

Custom fields let you store business-specific data on contact records. This quick-start covers reading field definitions, writing custom field values to contacts, and handling different field types through the API.

Prerequisites

Before working with Contact Fields, confirm you have:

• A GoHighLevel sub-account with custom fields already defined (or admin access to create them)
• A Private Integration Token with both the contacts and locations scopes configured
• At least one contact ID to test field updates on
• A REST client such as Postman, Insomnia, or curl

Set Up Authentication

Contact Fields require a Private Integration Token (PIT) with two scopes: contacts for reading and writing field values on contact records, and locations for retrieving custom field definitions.

Navigate to Settings > Integrations > Private Integrations in your sub-account. Create a new integration (or edit an existing one) and enable both the contacts and locations scopes.

Save and copy the token. Set your Authorization header to Bearer {your-pit-token} for all requests. Your base URL is https://services.leadconnectorhq.com.

If your existing PIT only has the contacts scope, you will need to add the locations scope to retrieve field definitions. Edit the integration and add the scope, then save.

Make Your First Call

Start by retrieving your custom field definitions to get the field IDs and types. Send a GET request to your location’s custom fields endpoint:

GET /locations/{locationId}/customFields
Authorization: Bearer {your-pit-token}

This returns all custom fields defined for the location, including their id, name, fieldKey, and dataType. Common data types include TEXT, NUMBER, DATE, SINGLE_OPTIONS (dropdown), and MULTIPLE_OPTIONS (multi-select).

To write a custom field value to a contact, include the customFields array in a PUT /contacts/{contactId} request:

PUT /contacts/{contactId}
Authorization: Bearer {your-pit-token}
Content-Type: application/json

{
  "customFields": [
    {
      "id": "field-id-here",
      "value": "Enterprise"
    }
  ]
}

Each object in the customFields array needs the field id (from the definitions endpoint) and the value you want to set.

Handle the Response

The custom fields endpoint returns a 200 status with an array of field definitions:

{
  "customFields": [
    {
      "id": "field-abc123",
      "name": "Account Tier",
      "fieldKey": "contact.account_tier",
      "dataType": "SINGLE_OPTIONS",
      "options": ["Starter", "Pro", "Enterprise"]
    },
    {
      "id": "field-def456",
      "name": "Annual Revenue",
      "fieldKey": "contact.annual_revenue",
      "dataType": "NUMBER"
    }
  ]
}

When writing values, match the data type. For SINGLE_OPTIONS, the value must be one of the defined options. For MULTIPLE_OPTIONS, pass an array of strings. For DATE, use ISO 8601 format. For NUMBER, pass a numeric value (not a string).

Common errors: 400 means the value does not match the field’s data type or is not a valid option. 404 means the field ID does not exist. 422 means the customFields array is malformed.

Test Your Setup

Run through this checklist to confirm custom field management is working:

1. List field definitions with GET /locations/{locationId}/customFields and note the IDs and data types
2. Set a text field on a test contact with PUT /contacts/{id} and a customFields entry
3. Read back the contact with GET /contacts/{id} and verify the custom field value appears
4. Test a dropdown field by setting a value from the options list. Then try setting an invalid value and confirm the API returns 400
5. Clear a field by setting the value to an empty string or null and verify it resets

Cross-check in the GoHighLevel UI. Open the contact record and scroll to the custom fields section. Values set via API should display exactly as they would if entered manually.

Next Steps

Read the full Contact Fields Guide for advanced patterns including field mapping for integrations and conditional field logic. Combine custom fields with Contact CRUD to set fields at creation time, or use Duplicate Finder to verify field data before enrichment workflows.