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.
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.
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.
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.
- Open the lookup field
Setup, Object Manager, source object, Fields & Relationships, click the lookup field.
- Open Lookup Filter section
Scroll to Lookup Filter. Click Edit Filter Criteria.
- 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.
- Choose Required or Optional
Required blocks save on non-matching values; Optional warns but allows. Pick based on data-quality importance.
- Set custom error message (Required only)
Write a clear, specific error message explaining the constraint.
- 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.
- 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
Cross-checked against the following references.
- Lookup FiltersSalesforce Help
- Create Lookup FiltersSalesforce Help
Straight from the source - Salesforce's reference material on Lookup Filter.
- Lookup Filter ConsiderationsSalesforce Help
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 discussion…