Salesforce Dictionary - Free Salesforce GlossarySalesforce Dictionary
DictionaryLLookup Filter
Core CRMBeginner

Lookup Filter

A Lookup Filter is a configuration on a Salesforce lookup field that narrows the records the user sees in the Lookup Dialog by applying admin-defined criteria.

§ 01

Definition

A Lookup Filter is a configuration on a Salesforce lookup field that narrows the records the user sees in the Lookup Dialog by applying admin-defined criteria. The filter evaluates each candidate record against the criteria; only records that match appear in the dialog. The filter can reference the source record''s fields, the target record''s fields, formulas, and user attributes, letting admins build context-aware filters like Contact.AccountId = $Source.AccountId or User.Profile.Name = ''Sales Manager''.

Lookup Filters are the standard tool for preventing data-quality problems at the source. Without a filter, a user filling in an Opportunity.PrimaryContact lookup sees every Contact in the org and may pick a wrong one. With a filter restricting the dialog to Contacts on the same Account, the wrong-record problem disappears. Filters can be required (block save when the chosen record fails the criteria) or optional (suggest but allow override). Admins configure them under the lookup field''s definition; once saved, every dialog opening of that field respects the filter.

§ 02

How Lookup Filters enforce data quality at the field level

Filter criteria syntax

Lookup Filter criteria support up to 10 conditions with AND/OR logic. Each condition references a field on the source record, the target record, a formula, or a user attribute. Common patterns: limit Contacts to those on the same Account as the source, limit Products to those in the same Pricebook, limit Cases to those owned by the current user.

Required vs. optional filters

Required filters block save if the user picks a record that fails the criteria. Optional filters surface a warning but allow the save. Most filters are required; optional filters are useful when admins want to guide users toward the right answer without blocking edge cases.

Common filter patterns

The most common pattern is same-Account: Contact.AccountId equals Source.AccountId, restricting an Opportunity''s Contact lookup to contacts on the deal''s Account. The same-record-type pattern limits by RecordTypeId. The active-only pattern filters by IsActive = true to exclude deactivated records. Custom-field-based filters target organization-specific data quality rules.

Filter messages

Required filters can include a custom error message displayed when the user picks a non-matching record. Good error messages explain the constraint: This Contact must belong to the same Account as the Opportunity. Generic messages confuse users; tailored messages save support tickets.

Filter performance

Lookup Filters evaluate at dialog-open time. Complex filters with many conditions or cross-object references can slow dialog response. Test with production data volumes; what feels fast in sandbox can lag at scale.

Filters and user permissions

Lookup Filters compose with record sharing. The dialog shows records that match the filter AND are accessible to the user. A filter that should match 1000 records but the user sees only 50 means the other 950 are blocked by sharing, not the filter. This combination can be confusing; impersonate a user to verify behavior.

Editing existing data

Lookup Filters apply to new edits and existing records on save. A record with a lookup value that no longer matches a newly-tightened filter cannot be saved without changing the lookup. Tightening filters on existing data requires a backfill plan.

§ 03

Configure a Lookup Filter on an existing field

Lookup Filter configuration is a few clicks within the field''s edit page. The art is picking the right criteria.

  1. Open the lookup field

    Setup, Object Manager, source object, Fields & Relationships, click the lookup field.

  2. Open Lookup Filter section

    Scroll to Lookup Filter. Click Edit Filter Criteria.

  3. Add filter conditions

    Add each condition: pick the field, the operator (equals, not equals, contains), and the value. Use $Source merge fields to reference the source record.

  4. Choose Required or Optional

    Required blocks save on non-matching values; Optional warns but allows. Pick based on data-quality importance.

  5. Set custom error message (Required only)

    Write a clear, specific error message explaining the constraint.

  6. Test as a regular user

    Impersonate a user with the relevant profile. Open the source record, click the lookup, verify the dialog shows only filtered records and the error message fires correctly.

Gotchas
  • Lookup Filters apply to existing records on next save. Tightening filters on populated data requires a backfill or careful change-management plan.
  • Filters compose with record sharing. Users see only records that match the filter AND that they have access to; the intersection can be confusing.
  • Complex filters slow dialog response. Test with production data volumes.
  • Required filters with vague error messages frustrate users. Write specific, actionable messages.
§

Trust & references

Sources

Cross-checked against the following references.

Official documentation

Straight from the source - Salesforce's reference material on Lookup Filter.

Keep learning

Hands-on resources to go deeper on Lookup Filter.

Was this entry helpful?
Help us write better definitions. Quick reactions or detailed edit suggestions.

About the Author

Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.

§

Test your knowledge

Q1. What does a Lookup Filter do?

Q2. Why use lookup filters?

Q3. What can lookup filter criteria reference?

§

Discussion

Loading…

Loading discussion…