Contact Search Syntax

Find a single contact or a group of contacts with the same fields or attributes using advanced search syntax.

The Contacts tab lets you search for contacts by name, email, phone number, or any of the custom fields you have set up. For simple lookups you can type a name, email, or phone number directly into the search box. To filter on a specific field, compare numbers and dates, or combine conditions, use the syntax described below.

The syntax is the same shape as the Appointment Search Syntax and Conversation Search Syntax — the supported fields are different but the operators and boolean rules work the same way.

Full Text Search

By default, Apptoto performs a full text search across each contact’s name, email, and phone number.

For example, to find any contact with “fred” in their name, email, or phone:

fred

To find contacts with both “fred” and “smith”:

fred smith

To find contacts with the exact phrase “fred smith” in them:

"fred smith"

Default Fields

The fields that are searched by default for a plain text query are:

• name: The contact’s name
• email: The contact’s email address
• phone: The contact’s phone number (matched against both the original and the normalized form)

Negative Search

To find all contacts that do not contain “haircut” in any of the default fields:

-haircut

or

!haircut

Field Search

You can search a specific field by putting the field name first. For example, to find contacts whose name contains “fred”:

name:fred

To find contacts whose email contains “protonmail.com”:

email:protonmail.com

If you want an exact match instead of a contains match, use the = operator:

email="fred@example.com"

The : and = in the above examples are called search “operators”. The following operators are available:

Operator	Data Types	Notes
:	text, date, number	For text fields, this performs a contains search. For date fields, it searches the entire day specified. For number fields, it does an exact match
=	text, date, number	Does an exact match. You can use * as a wildcard for text fields
!=	text, date, number	Not equal
>	date, number	Greater than
>=	date, number	Greater than or equal
<	date, number	Less than
<=	date, number	Less than or equal

Special Values

Use the special keyword “empty” to find contacts where a field is empty or missing. For example:

email = empty

finds all contacts with no email address. To find the opposite:

zip != empty

Special Date Phrases

For date fields, you can use “today”, “tomorrow”, “yesterday”, and “upcoming” as values.

To find all contacts added today:

created_at = today

To find all contacts added since yesterday:

created_at >= yesterday

Other dates can be written in human-readable form. For example:

created_at > "January 20th, 2026" and created_at < "January 30th, 2026"

finds contacts added between January 20th and January 30th, 2026. You can also use 2026-01-20 and 2026-01-30.

If you want to find all contacts added on a specific day, you can use the : operator. For example, the following finds all contacts added on March 2nd, 2026:

created_at:2026-03-02

Phone Number Searches

When you search by phone, Apptoto automatically normalizes the value you typed so it matches contacts regardless of how the phone was originally entered. For example, all of the following find a contact whose phone is stored as (415) 555-1234:

phone=+14155551234

phone:4155551234

phone:415-555-1234

Boolean Logic

By default, multiple terms are combined with AND. For example, fred smith finds contacts that match both “fred” AND “smith”.

To find contacts matching “fred” OR “smith”:

fred or smith

The or operator has lower precedence than and, so the following:

fred or smith and bob

is the same as:

fred or (smith and bob)

Use parentheses to change how the query is grouped. For example, to find contacts that match either “fred” or “smith” AND also “bob”:

(fred or smith) and bob

You can combine field-specific queries with boolean logic too:

(name:fred or name:smith) and zip:97201

Custom Fields

If your contacts have custom fields, you can search them with the custom. prefix. For example:

custom.referral_source:website

finds all contacts whose referral_source custom field contains “website”.

Defining a contact field

You can register a contact field under Settings > Field Settings in the portal by clicking +Add Custom Contact Field and giving it a name, a label, and a type (Number, Currency, Date, Date/Time, Text, String, Dropdown, or Checkbox). The first section of the Create and Map Apptoto Fields to Salesforce walkthrough shows the screen in action — the steps are the same whether or not you use Salesforce.

A “defined” field in the rest of this article means a field you have registered there.

Bare-name shorthand

For fields you have defined under Settings > Field Settings, you can drop the custom. prefix and use the field name directly:

referral_source:website

is the same as custom.referral_source:website. If a custom field shares a name with a built-in field like name, the built-in field wins and you need the custom. prefix to disambiguate.

If a piece of custom data exists on your contacts but you have not registered it under Field Settings (for example, free-form text added to a contact’s notes), the bare-name shorthand will not work and you need to use custom.NAME to reference it.

Custom field types

When you register a contact field under Settings > Field Settings, the type you pick controls how Apptoto searches it:

• Number and Currency fields are compared numerically, so the comparison operators (>, >=, <, <=) work as expected.
• Date and Date/Time fields support the date operators and special phrases described above.
• String, Text, Dropdown, and Checkbox fields are searched as text (contains for :, exact for =).

For example, if you have a Number-typed custom field called lifetime_value:

lifetime_value > 1000

Or if you have a Date-typed custom field called joined_at:

joined_at > "January 1st, 2026"

If a custom field has not been registered under Field Settings, Apptoto treats it as text by default, so a plain contains search like custom.foo:bar still works — but custom.foo > 1000 will compare values as text, not as numbers.

Contact Fields

Besides the default and custom fields above, the following built-in fields are available:

Field	Type	Description	Notes
name	text	The contact’s name	name:fred
zip	text	The contact’s postal code	zip:97201
notes	text	Notes saved on the contact	notes:vip
created_at	date	When the contact was added	created_at > today
updated_at	date	When the contact was last updated	updated_at >= yesterday
email	text	The contact’s email	email:protonmail.com
phone	text	The contact’s phone (any format)	phone=+14155551234
normalized_phone	text	The contact’s normalized phone	normalized_phone=+14155551234
external_id	text	The contact’s ID in your linked CRM or calendar	external_id=abc123
address_book_id	number	The address book the contact lives in	address_book_id:5