LookupFilter

Represents a lookup filter, which restricts the valid values and lookup dialog results for lookup, master-detail, and hierarchical relationship fields.

Available from Tooling API version 34.0 or later.

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

Version 

Introduced in API version 34.0.

Supported SOAP API Calls 

describeSObjects(), query(), retrieve()

Supported REST API Methods 

GET, HEAD, Query

Fields 

Active 

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Description: If true, the lookup filter is active.

• Default value: false

DeveloperName 

• Type: string

• Required: No

• Properties: Filter, Group, Sort

• Description: The unique name of the object in the API. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. In managed packages, this field prevents naming conflicts on package installations. With this field, a developer can change the object’s name in a managed package and the changes are reflected in a subscriber’s organization. Label is Record Type Name.

FullName 

• Type: string

• Required: No

• Properties: Create, Group, Nillable

• Description: The full name of the associated metadata object in Metadata API.

Query this field only if the query result contains no more than one record. Otherwise, an error is returned. If more than one record exists, use multiple queries to retrieve the records. This limit protects performance.

IsOptional 

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Description: Required. If true, the lookup filter is optional.

• Default value: false

ManageableState 

• Type: picklist

• Required: No

• Properties: Filter, Group, Nillable, Restricted picklist, Sort

• Description: Indicates the manageable state of the specified component that is contained in a package:

• beta

• deleted

• deprecated

• deprecatedEditable

• installed

• installedEditable

• released

• unmanaged

• Possible values:

  • beta — beta

  • deleted — deleted

  • deprecated — deprecated

  • deprecatedEditable — deprecatedEditable

  • installed — installed

  • installedEditable — installedEditable

  • released — released

  • unmanaged — unmanaged

Metadata 

• Type: complexvalue

• Required: No

• Properties: Create, Nillable, Update

• Description: The metadata for this lookup filter.

Query this field only if the query result contains no more than one record. Otherwise, an error is returned. If more than one record exists, use multiple queries to retrieve the records. This limit protects performance.

NamespacePrefix 

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Description: The namespace of the custom field, which is sometimes different from the object’s namespace.

SourceFieldDefinitionId 

• Type: string

• Required: No

• Properties: Filter, Group, Sort

• Description: Durable ID of the object specified in SourceFieldDefinition.

SourceObject 

• Type: picklist

• Required: No

• Properties: Filter, Group, Nillable, Restricted picklist, Sort

• Description: The object that contains the lookup field that uses this lookup filter. Null if the lookup filter doesn’t reference fields on the source object.

TargetEntityDefinitionId 

• Type: string

• Required: No

• Properties: Filter, Group, Sort

• Description: ID of the TargetEntityDefinition.

Example 

The Owner field on Account represents a user with certain characteristics.

In this example, SourceFieldDefinition is Account.Owner and TargetEntityDefinition is User, because Owner is a lookup field to User.

LookupFilter Metadata 

Metadata about the lookup filter is returned in the Metadata field:

Field Type Description active boolean Required. If true, the lookup filter is active. booleanFilter string The filter logic, if any, applied to this filter using Boolean operators AND, OR, or NOT. description string A description of the filter does. errorMessage string If the lookup filter fails, the error m. filterItems FilterItem Required. The set of filter conditions. Each lookup filter can have up to 10 FilterItems. infoMessage string Information displayed on the page to help the user. For example, explaining why some items are excluded in the lookup filter. isOptional boolean Required. If true, the lookup filter is optional.

FilterItem Metadata 

Represents one entry in a set of filter criteria.

Field Type Description field string Represents the field specified in the filter. operation FilterOperation, an enumeration of strings Valid values: equals notEqual lessThan greaterThan lessOrEqual greaterOrEqual contains notContain startsWith includes excludes within (DISTANCE criteria only) value string Represents the value of the filter item being operated upon. For example, if the filter is my_number_field__c > 1, the value of this field is 1. valueField string Specifies if the final column in the filter contains a field or a field value. Approval processes don’t support this field in filter criteria.