Methods

# static list(params) → {Promise.<ServiceResponse>}

Queries entities of a given type with optional filtering, full-text search, and field projection.

entityType (required) — selects which entity collection to query:

'ou' — Organisational Units
'person' — Persons
'group' — Groups

filterModel — structured filter applied on top of the full-text search. Each item targets a field and an operator:

filterModel: {
  logicOperator: 'and', // 'and' (default) or 'or'
  items: [
    { field: 'data.active', fieldType: 'boolean', operator: 'equals', value: true },
    { field: 'data.name',                         operator: 'contains', value: 'GmbH' }
  ]
}

String operators: contains, doesNotContain, startsWith, endsWith, equals, isEmpty, isNotEmpty. Boolean operators: equals, isEmpty, isNotEmpty.

Special virtual fields for relationship filtering:

__GROUPS__ — filter by group membership (value: humanId or array of humanId)
__MEMBERS__ — filter by group members
__EMPLOYEES__ — filter by employee humanId
__EMPLOYMENTS__ — filter by employment OU humanId
__ROLES__ — filter by role name across employees/employments

Relationship operators: includes (default) or excludes.

Special field aliases:

originalHumanId → resolves to humanId
contacts.<type> → resolves to the correct nested contact path (email, phone, mobile, fax)
data.bankHistory → resolves to data.bankHistory.iban

Parameters:

Name	Type	Attributes	Description
`params`	`Object`
`entityType`	`'ou'` \| `'person'` \| `'group'`		Entity collection to query. Required.
`fields`	`Array.<string>` \| `FieldMappingObject`	<optional>	Fields to return. Always includes `entityType`, `id`, `humanId`, and common name fields. Pass an array to add extra includes, or an object with `include`/`exclude` keys.
`filterModel`	`Object`	<optional>	Structured filter.
`quickFilter`	`string`	<optional>	Free-text search string matched against ngram-indexed fields.
`searchSubEntities`	`boolean`	<optional>	When `true`, extends `quickFilter` to also search nested employees (for OUs), employments (for persons), and members (for groups).
`hideInactive`	`boolean`	<optional>	When `true`, excludes entities where `data.active` is not `true`.
`idsOnly`	`boolean`	<optional>	When `true`, returns only `humanId` and `pathSegments.humanId` per entity.
`sort`	`Object`	<optional>	Sort configuration forwarded to Elasticsearch.

View Source services/CustomersService.class.js, line 158

Returns:

Type: Promise.<ServiceResponse>

Examples

// All active persons whose name contains "Müller"
const { result } = await customers.Entities.list({
  entityType: 'person',
  hideInactive: true,
  filterModel: {
    items: [{ field: 'data.lastName', operator: 'contains', value: 'Müller' }]
  }
})

// OUs that belong to a specific group, with free-text search
const { result } = await customers.Entities.list({
  entityType: 'ou',
  quickFilter: 'Engineering',
  filterModel: {
    items: [{ field: '__GROUPS__', operator: 'includes', value: 'group-abc123' }]
  }
})