Location Custom Fields Setup

Define and manage custom fields at the location level. Custom fields extend the data model for contacts, opportunities, and other objects within a sub-account. This quick-start covers creating field definitions, managing field types, and the full CRUD lifecycle.

Prerequisites

Before making your first Location Custom Fields call, confirm you have:

• A GoHighLevel sub-account with admin-level access
• Access to Settings > Integrations > Private Integrations in your sub-account
• A REST client such as Postman, Insomnia, or curl in your terminal
• Your sub-account’s locationId (found in Settings > Business Profile)
• Understanding of the custom field types you need (text, number, date, dropdown, checkbox, etc.)

Custom fields defined here appear in the contact form, opportunity records, and anywhere GHL supports custom data.

Set Up Authentication

All Location Custom Fields endpoints require a Private Integration Token (PIT) with the locations scope.

Navigate to Settings > Integrations > Private Integrations. Click Create New Integration, name it “Custom Fields API,” and enable the locations scope. Click Save and copy the generated token.

Pass this token in the Authorization header as a Bearer token. Set your base URL to https://services.leadconnectorhq.com. Include Content-Type: application/json and the Version: 2021-07-28 header.

Make Your First Call

Start by listing existing custom fields for your location:

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

To create a new custom field:

POST /locations/{locationId}/customFields
Authorization: Bearer {your-pit-token}
Content-Type: application/json

{
  "name": "Preferred Contact Method",
  "dataType": "SINGLE_OPTIONS",
  "options": ["Phone", "Email", "Text"],
  "placeholder": "Select preference",
  "position": 0
}

Supported dataType values include TEXT, LARGE_TEXT, NUMBER, PHONE, EMAIL, DATE, SINGLE_OPTIONS, MULTIPLE_OPTIONS, CHECKBOX, and FILE_UPLOAD. For dropdown and multi-select types, include an options array.

To update a field, use PUT /locations/{locationId}/customFields/{fieldId}. To delete, use DELETE /locations/{locationId}/customFields/{fieldId}.

Handle the Response

A successful POST returns a 200 status with the custom field object:

{
  "customField": {
    "id": "cf-001",
    "name": "Preferred Contact Method",
    "fieldKey": "contact.preferred_contact_method",
    "dataType": "SINGLE_OPTIONS",
    "options": ["Phone", "Email", "Text"],
    "position": 0
  }
}

The fieldKey is what you use when setting values on contacts via the Contact CRUD endpoint. Pass custom field values in the customFields array with the id and desired value.

Common errors: 400 means a required field is missing or the dataType is invalid. 401 means your token is invalid. 409 means a custom field with the same name already exists. 404 on update or delete means the field ID does not exist.

Test Your Setup

Run through this checklist to confirm everything works:

1. List existing custom fields with GET /locations/{locationId}/customFields
2. Create a test field with POST /locations/{locationId}/customFields using dataType: "TEXT"
3. Update the field name with PUT /locations/{locationId}/customFields/{fieldId}
4. Verify the field appears in Settings > Custom Fields in the GHL dashboard
5. Delete the test field with DELETE /locations/{locationId}/customFields/{fieldId}

After creating a custom field, test it end to end by setting a value on a contact through the Contact CRUD endpoint to confirm the field accepts data correctly.

Next Steps

Read the full Location Custom Fields Guide for field mapping strategies and data migration patterns. From here, explore Location Custom Values for managing dynamic variables and Contact CRUD for populating custom fields on contacts.