---
title: entities.customEntity
description: Read custom entity records with the customEntity repository, and change them with the custom entity mutations. Same records as the REST {custom_entity_api_name} entity.
canonical: https://developers.coevera.com/reference/graphql/custom-entity/
section: graphql
verification: schema
generatedFrom: schema f155746 (2026-10-20)
publisher: Coevera
---

# entities.customEntity

Read custom entity records with the customEntity repository, and change them with the custom entity mutations. Same records as the REST {custom_entity_api_name} entity.

REST: [{custom_entity_api_name}](https://developers.coevera.com/reference/rest/custom-entities.md).

## Queries

- `getById(entityId: ID!): CustomEntityEntity` Returns the record with the given id, or null when there is none. Deleted records are returned as well.
- `getByIds(entityIds: [ID!]!): [CustomEntityEntity!]!` Returns the records with the given ids; ids without a record are left out. Deleted records are returned as well.
- `getAll(limit: Int, offset: Int, filter: CustomEntityFilterInput, orderBy: [CustomEntityOrderByInput!], includeDeleted: Boolean): [CustomEntityEntity!]!` Returns the records that match the filter, paged with limit and offset.
- `getByCriteria(filter: CustomEntityFilterInput, orderBy: [CustomEntityOrderByInput!], includeDeleted: Boolean, before: String, after: String, first: Int, last: Int): CustomEntityEntityConnection` Returns the records that match the filter as a cursor-paginated connection.
- `getChangedFieldsSinceRevision(id: UUID!, revision: Int!): [UUID!]!` Returns the ids of the fields of a record that changed after the given revision. Returns an empty list for entities without change tracking.
- `getBySession(includedIds: [UUID!]!, excludedIds: [UUID!]!, sessionId: String!, before: String, after: String, first: Int, last: Int): CustomEntityEntityConnection` Returns a page of records selected in a list or report: all records of the given result plus the explicitly included ids, minus the excluded ids.
- `getByIdFormatted(id: UUID!, fieldIds: [UUID!]): JSONString` Returns the values of a record's fields formatted for display, keyed by field id.
- `autoPrefill(mappingId: UUID!, entityId: UUID!, targetEntityTypeId: UUID): CustomEntityEntity!` Returns a new, unsaved record pre-filled from a source record according to a field mapping. Nothing is saved; the returned values can be used as input for create.

## Mutations

- `changeOwnershipCustomEntity(input: ChangeOwnershipCustomEntityInput!): ChangeOwnershipCustomEntityPayload` Change owner. GraphQL only.
- `copyCustomEntity(input: CopyCustomEntityInput!): CopyCustomEntityPayload` Copy a record. GraphQL only.
- `manageSharingCustomEntity(input: ManageSharingCustomEntityInput!): ManageSharingCustomEntityPayload` Change who it is shared with. GraphQL only.

## Types

### CustomEntityEntity (object)

Record of a custom entity, a kind of record the space defines (such as Vehicle or Contract) in addition to the built-in entities.

- `customFields: JSONString! (1 args)` Values of the record's custom fields as a JSON object keyed by custom field apiName (camelCase).
- `pendingScheduledActions: Int` Filled only when a single record is read by its id; otherwise null or an empty list.
- `isDeleteProtected: Boolean!` True when the record is protected against deletion because it must always exist in the space. Deleting a record that is not protected can still fail on other checks. Read-only.
- `id: ID!` Unique identifier of entity.
- `isDeleted: Boolean` Specifies if the entity is considered deleted.
- `modified: DateTime` Last modification time.
- `created: DateTime` Creation time.
- `currencyExchangeRatesList: CurrencyExchangeRatesListEntity` Currency exchange rate list used to convert monetary fields linked to this record. Empty to inherit the team space default.
- `owner: ClientEntity` Sales user who owns this custom entity record.
- `type: CustomEntityTypeEntity` Custom entity type that classifies this record. Custom entity types are configurable per team space and define the schema (fields and form) of the records.
- `unit: SalesUnitEntity` Sales unit this record is assigned to. Determines which team members can see the record under unit-based sharing.
- `currencyExchangeRatesListId: ID` Id of the currency exchange rate list applied to this record.
- `name: String` Name of the entity and its default text representation.
- `ownerId: ID!` Id of the sales user who owns the custom entity record.
- `shareMode: ShareModeEnum` Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users).
- `tableName: String!` Discriminator identifying which custom entity type this record belongs to. Read-only; matches CustomEntityType.entityApiName and is used as the entity name in REST and GraphQL queries.
- `typeId: ID` Id of the custom entity type.
- `unitId: ID` Id of the sales unit.
- `sharingUnits: CustomEntitySharingSalesUnitRelationEntityConnection (8 args)` Sales units that have been granted shared access to this custom entity record. Editable only when shareMode allows unit sharing.
- `sharingClients: CustomEntitySharingClientRelationEntityConnection (8 args)` Users that have been granted shared access to this custom entity record. Editable only when shareMode allows user sharing.
- `documents: CloudObjectRelationEntityConnection (8 args)` Documents linked to this custom entity record.
- `staticProfiles: ProfileRelationEntityConnection (8 args)` Saved view profiles this custom entity record currently matches.
- `tags: TagRelationEntityConnection (8 args)` Tag labels applied to this custom entity record.
- `isFavorite: Boolean!` True when the current authenticated user has marked this record as favorite. Per-user.
- `revision: Int` Revision when entity was lastly changed.
- `viewerIdsPerSalesUnit: [UUID!]!` Filled only when a single record is read by its id; otherwise null or an empty list.
- `instancePermissions: [EntityPermsEnum!]! (1 args)` Permissions the current user has on this record, out of the requested ones.

### CustomEntityEntityConnection (object)

Paginated list of CustomEntity records.

- `pageInfo: PageInfo!` Pagination data for this connection.
- `edges: [CustomEntityEntityEdge]!` Contains the nodes in this connection.
- `totalCount: Int` Total number of items in the connection.

### CustomEntityEntityEdge (object)

A Relay edge containing a `CustomEntityEntity` and its cursor.

- `node: CustomEntityEntity` The item at the end of the edge
- `cursor: String!` A cursor for use in pagination

### CustomEntityFilterInput (input)

Filter conditions for CustomEntity records. Conditions on different fields are combined with AND; use OR, AND and NOT for other combinations.

- `OR: [CustomEntityFilterInput!]` Matches records that meet at least one of the listed filters.
- `AND: [CustomEntityFilterInput!]` Matches records that meet all of the listed filters.
- `NOT: CustomEntityFilterInput` Matches records that do not meet this filter.
- `globalSearchQuery: String` Search term matched against the fields that the global search covers for this entity.
- `id: EntityFilterStringField` Unique identifier of entity.
- `isDeleted: Boolean` Specifies if the entity is considered deleted.
- `modified: EntityFilterDateTimeField` Last modification time.
- `created: EntityFilterDateTimeField` Creation time.
- `currencyExchangeRatesListId: EntityFilterStringField` Id of the currency exchange rate list applied to this record.
- `name: EntityFilterStringField` Name of the entity and its default text representation.
- `ownerId: EntityFilterStringField` Id of the sales user who owns the custom entity record.
- `shareMode: ShareModeEnumFilterInput` Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users).
- `tableName: EntityFilterStringField` Discriminator identifying which custom entity type this record belongs to. Read-only; matches CustomEntityType.entityApiName and is used as the entity name in REST and GraphQL queries.
- `typeId: EntityFilterStringField` Id of the custom entity type.
- `unitId: EntityFilterStringField` Id of the sales unit.
- `revision: EntityFilterNumberField` Revision when entity was lastly changed.
- `withCustom: [CustomField!]` Conditions on custom fields, each identified by its api name. All listed conditions must match.
- `currencyExchangeRatesList: CurrencyExchangeRatesListFilterInput` Currency exchange rate list used to convert monetary fields linked to this record. Empty to inherit the team space default. Matches records where a related record meets these conditions.
- `owner: ClientFilterInput` Sales user who owns this custom entity record. Matches records where a related record meets these conditions.
- `type: CustomEntityTypeFilterInput` Custom entity type that classifies this record. Custom entity types are configurable per team space and define the schema (fields and form) of the records. Matches records where a related record meets these conditions.
- `unit: SalesUnitFilterInput` Sales unit this record is assigned to. Determines which team members can see the record under unit-based sharing. Matches records where a related record meets these conditions.
- `sharingUnits: CustomEntitySharingSalesUnitRelationFilterInput` Sales units that have been granted shared access to this custom entity record. Editable only when shareMode allows unit sharing. Matches records where a related record meets these conditions.
- `sharingClients: CustomEntitySharingClientRelationFilterInput` Users that have been granted shared access to this custom entity record. Editable only when shareMode allows user sharing. Matches records where a related record meets these conditions.
- `documents: CloudObjectRelationFilterInput` Documents linked to this custom entity record. Matches records where a related record meets these conditions.
- `staticProfiles: ProfileRelationFilterInput` Saved view profiles this custom entity record currently matches. Matches records where a related record meets these conditions.
- `tags: TagRelationFilterInput` Tag labels applied to this custom entity record. Matches records where a related record meets these conditions.

### CustomEntityOrderByInput (input)

Sorting of CustomEntity records. Set exactly one field in each item; list several items to sort by more fields, in order of priority.

- `id: OrderByEnum` Unique identifier of entity.
- `isDeleted: OrderByEnum` Specifies if the entity is considered deleted.
- `modified: OrderByEnum` Last modification time.
- `created: OrderByEnum` Creation time.
- `currencyExchangeRatesList: [CurrencyExchangeRatesListOrderByNestedInput!]` Currency exchange rate list used to convert monetary fields linked to this record. Empty to inherit the team space default. Sorts by fields of the related record, listed in order of priority.
- `owner: [ClientOrderByNestedInput!]` Sales user who owns this custom entity record. Sorts by fields of the related record, listed in order of priority.
- `type: [CustomEntityTypeOrderByNestedInput!]` Custom entity type that classifies this record. Custom entity types are configurable per team space and define the schema (fields and form) of the records. Sorts by fields of the related record, listed in order of priority.
- `unit: [SalesUnitOrderByNestedInput!]` Sales unit this record is assigned to. Determines which team members can see the record under unit-based sharing. Sorts by fields of the related record, listed in order of priority.
- `currencyExchangeRatesListId: OrderByEnum` Id of the currency exchange rate list applied to this record.
- `name: OrderByEnum` Name of the entity and its default text representation.
- `ownerId: OrderByEnum` Id of the sales user who owns the custom entity record.
- `shareMode: OrderByEnum` Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users).
- `typeId: OrderByEnum` Id of the custom entity type.
- `unitId: OrderByEnum` Id of the sales unit.
- `revision: OrderByEnum` Revision when entity was lastly changed.
- `withCustom: CommonEntityRepositoryOrderByCustomField` Sorts by a custom field.

### ChangeOwnershipCustomEntityInput (input)

Parameters of the changeOwnershipCustomEntity mutation.

- `ownerId: ID!` User who becomes the new owner of the record.
- `unitId: ID!` Sales unit the record is assigned to.
- `keepOwnerAsEditor: Boolean!` When true, the previous owner (if still an active user) stays on the record as a shared user with the Editor role, and a Private sharing mode is switched to Standard.
- `transferLinkedRecords: Boolean!` When true, the new owner and sales unit are also applied to the record's open tasks and appointments and its notes. Linked records that cannot be transferred are skipped without failing the mutation.
- `id: ID!` Identifier of the CustomEntityEntity to perform the action on.
- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).

### CopyCustomEntityInput (input)

Parameters of the copyCustomEntity mutation.

- `skipCopySuffix: Boolean` When true, the copy keeps the original name without the copy suffix. Defaults to false.
- `id: ID!` Identifier of the CustomEntityEntity to perform the action on.
- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).

### CreateCustomEntitySharingClientRelationNoCustomEntityBackrefInput (input)

Field values of a new CustomEntitySharingClientRelation record, created together with the record it belongs to.

- `modified: DateTime` Last modification time.
- `created: DateTime` Creation time.
- `clientId: ID!` Id of the user.
- `role: SharingRoleEnum` Access the sharing gives the user on the custom entity record: Watcher can view it, Editor can view and edit it.
- `revision: Int` Revision when entity was lastly changed.

### CreateCustomEntitySharingSalesUnitRelationNoCustomEntityBackrefInput (input)

Field values of a new CustomEntitySharingSalesUnitRelation record, created together with the record it belongs to.

- `modified: DateTime` Last modification time.
- `created: DateTime` Creation time.
- `role: SharingRoleEnum` Access the sharing gives the sales unit on the custom entity record: Watcher can view it, Editor can view and edit it.
- `unitId: ID!` Id of the sales unit.
- `revision: Int` Revision when entity was lastly changed.

### ManageSharingCustomEntityInput (input)

Parameters of the manageSharingCustomEntity mutation.

- `shareMode: ShareModeEnum!` Sharing mode of the record: Standard, Private, AllView or AllEdit.
- `sharingClients: [CreateCustomEntitySharingClientRelationNoCustomEntityBackrefInput!]` Users the record is shared with, each with the Watcher (view) or Editor (edit) role. Send an empty list to remove all shared users.
- `sharingUnits: [CreateCustomEntitySharingSalesUnitRelationNoCustomEntityBackrefInput!]` Sales units the record is shared with, each with the Watcher or Editor role. Send an empty list to remove all shared units.
- `id: ID!` Identifier of the CustomEntityEntity to perform the action on.
- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).

### ChangeOwnershipCustomEntityPayload (object)

Result of the changeOwnershipCustomEntity mutation.

- `result: CustomEntityEntity` The record with its new owner.
- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).

### CopyCustomEntityPayload (object)

Result of the copyCustomEntity mutation.

- `result: CustomEntityEntity` The new record.
- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).

### ManageSharingCustomEntityPayload (object)

Result of the manageSharingCustomEntity mutation.

- `result: CustomEntityEntity` The record with its updated sharing.
- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).

Types several repositories share, such as `PageInfo` and the filter fields, are in the [types index](https://developers.coevera.com/reference/graphql/types.md). The [SDL](https://developers.coevera.com/graphql/schema.graphql) has the whole schema in one file.

## Example

```graphql
query FirstCustomEntitys {
  entities {
    customEntity {
      getByCriteria(first: 3, orderBy: [{ modified: Desc }]) {
        totalCount
        edges { node { id name modified } }
      }
    }
  }
}
```

```bash
curl 'https://{region}.api.coevera.com/api/v100/app/space/{space_id}/graphql/public' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{"query":"query FirstCustomEntitys { entities { customEntity { getByCriteria(first: 3, orderBy: [{ modified: Desc }]) { totalCount edges { node { id name modified } } } } } }"}'
```