Lookup Filter
A filter applied to a Salesforce lookup or master-detail relationship field that restricts which records are available for selection based on specified criteria.
Definition
A filter applied to a Salesforce lookup or master-detail relationship field that restricts which records are available for selection based on specified criteria. It prevents users from choosing invalid related records.
In plain English
“A Lookup Filter restricts which records show up when a user uses a lookup field to select a related record. So if you have a lookup to Contact on a custom object, you can use a filter to show only active contacts from a specific account, preventing users from picking the wrong record.”
Worked example
At Northwind Trading, sales reps creating a new Opportunity used to be able to pick any Contact in the org as the Primary Contact - leading to mistakes where Contacts from unrelated Accounts ended up linked to deals. The admin adds a Lookup Filter on the Primary Contact field: only Contacts whose Account matches the Opportunity's Account appear in the picker. The wrong-Contact problem disappears overnight, and downstream reports that join Opportunity to Contact stop producing inexplicable cross-account results.
Why Lookup Filter matters
A Lookup Filter is a configuration applied to a Salesforce lookup or master-detail relationship field that restricts which records are available for selection based on specified criteria. Filters can reference fields on the source object, the target object, the user, or the parent record, enabling sophisticated relationship constraints. For example, a Contact lookup on a custom object might filter to show only contacts where IsActive = true, or where Account.Type = 'Customer'.
Lookup filters are foundational to data quality because they prevent users from selecting invalid related records. Without them, users might pick inactive contacts, wrong-account opportunities, or other mismatches. With filters, the platform enforces correct relationships at the UI level. Filters can be required (blocking selection of non-matching records) or optional (showing matching records first but allowing override). Mature orgs use filters extensively to enforce data integrity through configuration rather than relying on user attention.
How to set up Lookup Filter
Lookup Filters narrow down what users can pick in a Lookup field — "only Active Accounts," "only Contacts at this Account," "only Users in the same Role." They tighten data quality without scaring users with validation errors after the save.
- Open Object Manager → object → Fields & Relationships → [Lookup field]
Click into the Lookup field's detail page (not edit, the detail).
- Click Edit
Top-right of the field detail page.
- Scroll to Lookup Filter section → Show Filter Settings
It's collapsed by default.
- Add filter criteria
Field, Operator, Value. Multiple rows are AND by default — the Filter Logic field at the bottom lets you write OR.
- Pick Required vs Optional Filter
Required: violations block save (UI and API). Optional: lookup popup hides non-matches but doesn't block API submission.
- Set Error Message (for Required filters)
What users see when they violate the filter. Use it to point them at the right path.
- Tick Active → Save
Activate the filter. Inactive filters don't fire.
Required (blocks save) or Optional (UI-only restriction).
Field-Operator-Value rows + Filter Logic for OR/parens.
Use $Source.<field> to reference the record being edited; otherwise references the target object.
What users see on violation. Plain text.
On = enforced. Off = saved but ignored.
- Required filter blocks the API too — including Apex DML, integrations, and Data Loader. Cross-check before activating that no integration is creating records that violate the new rule.
- Optional filter is purely UI — it does not constrain the API. Bad data can still flow in via the API; users just can't pick it from the dropdown.
- Cross-object filters use $Source.field syntax. Forgetting the $Source. prefix references the target object instead of the record being edited — confusing failures.
How organizations use Lookup Filter
Uses lookup filters to ensure users only see active records when selecting related contacts, preventing data quality issues from inactive selections.
Built filters that restrict opportunity-to-contact relationships based on account membership, preventing cross-account mismatches.
Treats lookup filters as a core data quality tool, configuring them on every relationship field where validity matters.
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…