Contacts

Contacts represent the people your agents will call. Each contact can have associated metadata that gets injected into conversations.

What is a Contact?

A contact stores:

Basic Info - Name, phone number, email
Metadata - Custom fields relevant to your use case
History - Previous conversations with this contact

Contact Properties

Property	Description
`id`	Unique identifier (UUID)
`workspaceId`	The workspace this contact belongs to
`firstName`	Contact’s first name
`lastName`	Contact’s last name
`phone`	Phone number in E.164 format
`email`	Email address
`metadata`	Custom JSON object with additional data
`createdAt`	When the contact was created
`updatedAt`	When the contact was last modified

Phone Number Format

All phone numbers must be in E.164 format:

+[country code][subscriber number]

+14155551234

Using Metadata

Metadata lets you store custom data that can be used in agent conversations:

{
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+14155551234",
  "metadata": {
    "accountNumber": "AC-12345",
    "preferredLanguage": "Spanish",
    "lastPurchaseDate": "2024-01-15",
    "vipStatus": true
  }
}

These values can be referenced in your agent’s system prompt using {{contact.customFields.<fieldName>}} syntax.

Custom fields

Custom fields are workspace-level fields that show up on every contact. Define them once in Settings > Custom Fields and they appear on the Contacts page and in workflow conditions.

Field types

Each custom field has a type that controls how it’s stored, validated, and rendered in the dashboard.

Type	Stored as	Contacts page input	Use for
Text	string	Single-line text input	Account numbers, notes, identifiers
Number	number	Numeric input (digits, decimals, negatives)	Budget, quantity, score
Date	ISO 8601 date string (`YYYY-MM-DD`)	Date picker	Renewal date, last contact, birthday
Boolean	true/false	Toggle / checkbox	VIP, opted-in, qualified

The type is set when the field is created and can’t be changed afterwards. Delete and re-create the field if you need a different type.

Where field types apply

Contacts page — the cell renders the right input for the type. Number cells reject non-numeric input, date cells open a calendar picker, boolean cells show a toggle.
Filters — date fields support Before, After, Equals, and In Between operators (see Condition action → Operators). Number fields support numeric comparisons. Booleans support Is true / Is false.
Workflow conditions — the same operators are available when a custom field is referenced inside a workflow.
API and integrations — custom field values are returned in their typed form on agent webhooks and the contact APIs. The GoHighLevel sync auto-creates fields as text — that behavior is unchanged.

In agent prompts

Reference any custom field in a prompt or opening line:

Hi {{contact.firstName}}, I see your renewal is on {{contact.customFields.renewalDate}}.

Saved views

Save the filters and sort you use most often as a named view. Each view is a preset of filters, sort order, and visible columns on the Contacts page — pick one from the view switcher and the page reconfigures instantly. Built-in views:

All Contacts — every contact in the workspace, no filters, default sort. Always available, can’t be deleted.

Creating a view:

On the Contacts page, set the filters, sort, and columns you want.
Click the view switcher and choose Save as view.
Give the view a name and save.

Saved views are workspace-scoped — anyone in the workspace can use them. Update or delete a view from the same dropdown. Views you create persist across sessions and devices. Common patterns:

New leads this week — filter by tag lead + created within the last 7 days
Renewals due — filter by custom date field renewalDate between today and end of month
Opted-out contacts — filter by SMS opt-out status to audit compliance

​Contacts

​What is a Contact?

​Contact Properties

​Phone Number Format

​Using Metadata

​Custom fields

​Field types

​Where field types apply

​In agent prompts

​Saved views

​API Operations