Methods

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

Queries entities across one or more types with optional filtering and field projection.

entityTypes (required) — one or more entity collections to query:

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

filterModel — structured filter:

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`
`entityTypes`	`Array.<('ou'\|'person'\|'group')>`		Entity collections 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.
`hideInactive`	`boolean`	<optional>	When `true`, excludes entities where `data.active` is not `true`.
`sort`	`Object`	<optional>	Sort configuration forwarded to Elasticsearch.

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

Returns:

Type: Promise.<ServiceResponse>

Example

const { result } = await customers.Entities.list({
  entityTypes: ['person'],
  hideInactive: true,
  filterModel: {
    items: [{ field: 'data.lastName', operator: 'contains', value: 'Müller' }]
  }
})

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

Searches entities of a single type using the full entity graph query engine.

Unlike Entities.list, this targets a single entityType and adds full-text search, sub-entity search, and idsOnly projection. For multi-type queries without these features, use Entities.list instead.

Parameters:

Name	Type	Attributes	Description
`params`	`Object`
`entityType`	`'ou'` \| `'person'` \| `'group'`		Entity type to search. Required.
`fields`	`Array.<string>` \| `FieldMappingObject`	<optional>	Fields to return. Always includes `entityType`, `id`, `humanId`, and common name fields.
`filterModel`	`Object`	<optional>	Structured filter (same schema as `Entities.list`).
`quickFilter`	`string`	<optional>	Free-text search against ngram-indexed fields.
`searchSubEntities`	`boolean`	<optional>	Extends `quickFilter` to nested employees, employments, or members depending on entity type.
`hideInactive`	`boolean`	<optional>	Exclude entities where `data.active` is not `true`.
`idsOnly`	`boolean`	<optional>	Return only `humanId` values (and `pathSegments.humanId`).
`sort`	`Object`	<optional>	Sort configuration forwarded to Elasticsearch.

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

Returns:

Type: Promise.<ServiceResponse>

Example

const { result } = await customers.Entities.search({
  entityType: 'person',
  quickFilter: 'Müller',
  hideInactive: true
})