Lookup Filters

A Lookup Filter restricts which records a Lookup or Master-Detail field may point to. For example, an Account lookup on Contract__c can be filtered so only Partner accounts are selectable. Filters live on the field itself and are managed by the same PATCH that updates the field.

Create a Field With Its Filter (One Call)

POST /api/3.0/entity/EntityField
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "EntityId": "7NS0000000000A50001",
  "Name": "Account",
  "Label": "Account",
  "FieldTypeId": "7NY0000000000060000",
  "RelatedToEntityId": "7NS0000000000010001",
  "RelatedToRelationshipName": "Contracts",
  "LookupFilter": {
    "IsActive": true,
    "ErrorMessage": "Account must be a Partner",
    "LookupFilterCriteria": [
      {
        "FieldId": "7NX0000000000AC0001",
        "Operator": "equals",
        "Type": "Value",
        "Value": "Partner"
      }
    ]
  }
}

A filter must have at least one criterion.
Each criterion's FieldId references a field on the target entity (the entity being looked up), not the entity that owns the lookup.
The linking IDs (EntityFieldId on the filter, LookupFilterId on each criterion) are set by the platform automatically. Omit them.

Update a Filter

PATCH the field with the complete filter payload. The supplied criteria replace all existing criteria on the field — there is no partial update:

PATCH /api/3.0/entity/EntityField/<field id>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "Label": "Partner Account",
  "LookupFilter": {
    "IsActive": true,
    "ErrorMessage": "Account must be an active Partner",
    "LookupFilterCriteria": [
      { "FieldId": "7NX0000000000AC0001", "Operator": "equals", "Type": "Value", "Value": "Partner" },
      { "FieldId": "7NX0000000000AD0001", "Operator": "equals", "Type": "Value", "Value": "true" }
    ]
  }
}

LookupFilter DTO

Property	Type	Notes
`IsActive`	bool	Whether the filter is enforced. Defaults to `true`. Set to `false` to disable the filter without deleting the criteria.
`ErrorMessage`	string (≤80)	Message shown when a chosen record fails the filter.
`LookupWindowMessage`	string (≤255)	Helper text shown in the record picker.
`FilterLogic`	string	Advanced grouping expression. Omit for plain AND-across-all-criteria. See below.
`LookupFilterCriteria`	array	Required. One or more criteria.

LookupFilterCriterion DTO

Property	Type	Notes
`FieldId`	string	Required. EntityField ID on the target (looked-up) entity to test.
`Operator`	string	Required. Comparison operator. See the exact strings below.
`Type`	string	Required. `"Value"` to compare to a literal, `"Field"` to compare to another field on the same target record.
`Value`	string (≤255)	Required when `Type = "Value"`, except for `equals` / `not equals to` , which may be left empty to test for a blank value.
`ValueEntityFieldId`	string	Required when `Type = "Field"`.
`SequenceNo`	int	1-based position. Only needed when `FilterLogic` is set.

Operator Strings

Send the operator string exactly as listed — including the two quirks below:

Operator string	Meaning
`equals`	equal to
`not equals to`	not equal to — note the trailing space
`greater than`	>
`less than`	<
`less or equal`	≤
`greator or equal`	≥ — note the misspelling
`contains`	substring match
`does not contain`	negated substring
`starts with`	prefix match

Rollup filters use a different operator set. Do not use these strings for RollupFilterCriteria. See Rollup Summary Fields for the rollup-side operator list.

FilterLogic (Advanced)

By default, all criteria are AND-ed. To combine with OR or grouping, set FilterLogic and give each criterion a SequenceNo:

{
  "LookupFilter": {
    "IsActive": true,
    "FilterLogic": "1 AND (2 OR 3)",
    "LookupFilterCriteria": [
      { "SequenceNo": 1, "FieldId": "7NX0000000000AC0001", "Operator": "equals",       "Type": "Value", "Value": "Partner" },
      { "SequenceNo": 2, "FieldId": "7NX0000000000AE0001", "Operator": "equals",       "Type": "Value", "Value": "Hot" },
      { "SequenceNo": 3, "FieldId": "7NX0000000000AF0001", "Operator": "greater than", "Type": "Value", "Value": "1000000" }
    ]
  }
}

The number of criteria referenced in FilterLogic must equal the number of criteria in the array. Sequence numbers do not have to be contiguous but must be unique.

<< Picklists and Global Picklists | Rollup Summary Fields >>

Table of Contents