Lookup Filter
A Lookup Filter is an admin-defined rule on a Salesforce relationship field that restricts which records a user can pick.
Definition
A Lookup Filter is an admin-defined rule on a Salesforce relationship field that restricts which records a user can pick. It applies to lookup, master-detail, and hierarchical relationship fields. The filter limits both the valid values and the results shown in the lookup dialog. Each candidate record is checked against the criteria, and only matching records become selectable. Criteria can reference fields on the source record, fields on the target (lookup) object, fields on the running user, and fields one relationship away from the target.
How Lookup Filters keep relationships honest
What a Lookup Filter controls
A Lookup Filter governs the choices presented when a user fills in a relationship field. The relationship field can be a standard lookup, a master-detail field, or a hierarchical field like the Manager field on User. When the user opens the picker, the filter runs and the dialog returns only records that satisfy the criteria. The filter also guards the saved value, so a record set through automation or import can be checked too, depending on how the filter is configured. The point is data quality at the moment of entry. Without a filter, an Opportunity Contact lookup shows every Contact in the org, and a rushed user can link a Contact from the wrong company. With a filter that limits the dialog to Contacts on the deal Account, the wrong choice never appears. Salesforce documents this as restricting valid values and lookup dialog results. The filter is configured on the field itself, so it follows that field everywhere the field is edited, across page layouts, Lightning record pages, and the lookup dialog. One definition, consistent behavior.
The four sources a filter can reference
Filter criteria draw from four places, and knowing them is the key to writing a good filter. First, the source record, meaning the record being edited that holds the lookup field. You reference its fields with the $Source token, as in $Source.AccountId. Second, the target object, meaning the records on the other side of the lookup that the user is choosing from. Third, the running user, including fields on the User record, the Profile, and the Role, which lets a filter behave differently for a sales rep versus a manager. Fourth, fields that sit one relationship away from the target object, which extends reach without a formula. A condition compares one of these to a value or to another field. A classic example sets the Case Contact field so the dialog only returns Contacts whose Account matches the Account already chosen on the Case. That single rule stops a large share of mismatched data. Because the source side reads live from the open form, the filter reacts to what the user has entered so far in the same record.
Required versus optional filters
Every Lookup Filter is either required or optional, and the choice changes how strict it is. A required filter enforces the criteria. If a user, an import, or an API call tries to save a value that does not match, the save is blocked and the field shows an error. This is the right setting when a bad relationship would corrupt reporting or break downstream automation. An optional filter is softer. It still narrows the lookup dialog to matching records by default, but the user can switch the dialog to show all records and pick something outside the criteria. Optional filters suit cases where the criteria describe the usual answer but valid exceptions exist. A useful habit is to start optional while you watch how people actually use the field, then promote the filter to required once you trust the rule. Keep in mind that required filters reach beyond the screen. Because they validate on save, they can reject data loaded through Data Loader or an integration, so test those paths before you flip a filter to required in production.
Writing clear filter error messages
When a required filter rejects a value, Salesforce shows a message you control. The default text is vague and leaves users guessing why their pick was refused. A specific message turns a dead end into a quick fix. Compare a generic line like Value does not meet filter criteria with a tailored line such as The Contact you select must belong to the same Account as this Case. The second version names the constraint and tells the user how to comply. Good messages cut support tickets because the person fixing the record understands the rule immediately. Treat the message as part of the design, not an afterthought. Write it in plain language, name the related field involved, and avoid internal jargon that only the admin team understands. If the same rule appears on several fields, keep the wording consistent so users learn the pattern. The message only shows for required filters, since optional filters let the user proceed. That makes the message even more important, because it is the only explanation the user gets before the save fails.
Filters, sharing, and the records a user sees
A Lookup Filter is not the only thing deciding what shows in the dialog. The result is the intersection of the filter and the sharing model. A record must match the criteria and be visible to the running user through the org-wide defaults, role hierarchy, and sharing rules. This combination causes one of the most common support puzzles. An admin writes a filter expected to return a thousand records, but a sales rep sees only fifty. The filter is fine. The other records are hidden by sharing, so they were never candidates. When a lookup looks wrong, separate the two layers before changing anything. Reproduce the issue as the affected user, since an admin with broad access sees a different result set. The Salesforce best-practice guidance is to confirm whether sharing or the filter is the real cause. If sharing is the limiter, the fix lives in the sharing model, not the filter criteria. Treating every empty lookup as a filter bug leads to over-loosened filters that then let bad data back in. Diagnose the layer first, then act on the right one.
Dependent lookups and chained pickers
Because a filter can read the source record live, you can chain two lookups so the second depends on the first. Salesforce calls this a dependent lookup. The classic pattern is Account then Contact on the same record. The Contact lookup carries a filter comparing the Contact Account to the Account already selected on the source record. Pick the Account first, and the Contact dialog narrows to people at that company. Change the Account, and the Contact set updates to match. This guides users down a logical path without custom code and keeps related fields in agreement. The order of entry matters, so place the controlling field, the Account here, above the dependent field on the layout, and tell users to fill them top to bottom. If the dependent field is set before the controlling one, the filter has nothing to compare against yet. Dependent lookups pair well with required filters when the relationship must always hold, and with optional filters when you want to suggest the right contacts while still allowing a rare cross-account link. Either way the user gets a shorter, more relevant list.
Performance and tightening filters on existing data
Two practical concerns come up once filters are live. The first is performance. A filter with many conditions, or one that reaches across objects, does more work each time the dialog opens. In a small sandbox it feels instant. Against production record volumes it can lag. Test with realistic data so you catch a slow filter before users do, and prefer indexed fields and simple comparisons where you can. The second concern is changing a filter on data that already exists. When you tighten the criteria, records whose current lookup value no longer matches do not silently break, but they become hard to edit. The next time someone saves such a record through a required filter, the save fails until the lookup is corrected. That can surprise users and stall routine edits. Before tightening a required filter in production, run a report to find records that would fail, and plan a backfill to update them. Salesforce also caps how many active filters an object can have, so audit existing filters before adding more. Roll changes out in a sandbox first, then schedule the production change when you can support the cleanup.
How to add a same-Account lookup filter to a Case Contact field
You define a Lookup Filter on the relationship field itself in Object Manager. The example below restricts a Case Contact lookup to Contacts on the same Account as the Case, the most common dependent-lookup pattern.
- Open the field in Object Manager
From Setup, go to Object Manager and select the object that holds the lookup field, for example Case. Open Fields and Relationships, click the relationship field name such as Contact Name, then click Edit.
- Show the filter settings
In the Lookup Filter section, click Show Filter Settings. This reveals the criteria builder where you add conditions that each candidate record must satisfy.
- Build the criteria
Add a condition comparing a target field to a source field. For the same-Account rule, set Contact: Account ID equals Field and choose $Source.Account ID. Add more rows and combine them with AND or OR if you need several conditions.
- Choose required or optional and write the message
Select Required to block non-matching saves, or Optional to default the dialog while allowing overrides. For a required filter, enter a clear custom error message that names the rule.
- Activate and test
Make the filter active, save, then test by editing a record. Confirm the dialog returns only matching records and that the controlling field sits above the dependent field on the layout.
The rows that each candidate record must satisfy; reference source fields, target fields, user fields, or fields one hop from the target.
Required enforces the rule on save and blocks bad values; Optional narrows the dialog by default but lets users show all records.
Shown for required filters when a save fails; write plain text that names the constraint and the related field.
Toggles the filter on or off without deleting it; objects have a cap on active filters, so deactivate unused ones.
- An empty or short lookup list is often sharing, not the filter; reproduce as the affected user before loosening criteria.
- Required filters validate on save, so they can reject Data Loader and API records; test those paths before going live.
- Place the controlling field above the dependent field on the layout, or the dependent filter has nothing to compare against.
- Tightening a filter can lock existing records that no longer match; report on and backfill them before flipping to required.
Prefer this walkthrough as its own page? How to Lookup Filter in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- Lookup FiltersSalesforce
- Lookup Filters Best PracticesSalesforce
Straight from the source - Salesforce's reference material on Lookup Filter.
- Define Lookup FiltersSalesforce
- LookupFilter (Tooling API)Salesforce
Hands-on resources to go deeper on Lookup Filter.
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 required Lookup Filter do when a user selects a record that fails the filter criteria?
Q2. Which is the most common Lookup Filter pattern used to keep related records consistent on a deal?
Q3. Why might a Lookup Filter that should match 1,000 records show a user only 50?
Discussion
Loading discussion…