Users

Use Cases

Get single user

Retrieves a single specific user via id, ref or email. Useful for displaying user profiles or checking status.

query {
  user(id: "uuid-here") {
    id
    name
    email
    ref
    archived
    roles
    language
    participantGroups { id name }
    managerGroups { id name }
  }
}

You can also look up users by ref or email:

query {
  user(ref: "your-external-id") { id name email }
}

Get list

Returns a paginated list of users. Supports filtering, sorting and search.

query {
  paginatedUsers(first: 50, archived: false) {
    edges {
      node {
        id
        name
        email
        ref
        archived
        roles
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    count
  }
}

Available filters for paginatedUsers:

Create user

Creates a new user. An invitation email is sent by default unless sendInvite: false is set.

mutation {
  createUser(
    sendInvite: true
    user: {
      email: "jane@example.com"
      name: "Jane Doe"
      ref: "EMP-12345"
      roles: [MANAGER]
      language: NL
      addParticipantGroups: ["group-uuid-1"]
      addManagerGroups: ["group-uuid-2"]
    }
  ) {
    user {
      id
      name
      email
      ref
    }
    created
  }
}

Update user

Modifies an existing user based on id or ref.

mutation {
  updateUser(
    ref: "EMP-12345"
    user: {
      name: "Jane Smith"
      roles: [TRAINER]
      addParticipantGroups: ["group-uuid-3"]
      removeParticipantGroups: ["group-uuid-1"]
    }
  ) {
    user {
      id
      name
      roles
      participantGroups { id name }
    }
  }
}

Create or update (recommended for sync)

Looks up a user based on email or ref, and creates one if it doesn't exist. This is the recommended mutation for integrations as it handles both creation and updates in a single call.

mutation {
  updateOrCreateUser(
    email: "jane@example.com"
    sendInvite: false
    user: {
      name: "Jane Doe"
      ref: "EMP-12345"
      roles: [TRAINER]
      language: NL
    }
  ) {
    user {
      id
      name
      email
      ref
    }
    created
  }
}

The created field in the response tells you whether the user was newly created (true) or updated (false).

Archive/deactivate

Archives one or more users. These users are deactivated without permanently deleting them.

mutation {
  archiveUsers(
    archive: true
    ids: ["uuid-1", "uuid-2"]
  ) {
    response {
      succeededIds
      failedIds
    }
  }
}

To reactivate archived users, use archive: false.

GraphQL Definitions

Type

type User {
  id: ID!
  modelId: ID!
  email: String
  name: String!
  archived: Boolean!
  archivedAt: DateTime
  ref: String
  roles: [Role]
  profileImage: File!
  language: Language!
  extraFields: JSONString
  extraFieldsProfile: JSONString
  hasPassword: Boolean
  participantGroups: [Group!]
  managerGroups: [Group!]
  groupCount: Int
  invitedOn: DateTime
  lastLogin: DateTime
  userVia: [UserVia!]
}

Queries

user(id: UUID, ref: String, email: String): User

paginatedUsers(
  q: String
  archived: Boolean
  extraCategories: [ExtraCategoryFilterInput]
  lastLogin_Gt: DateTime
  lastLogin_Lt: DateTime
  userRoles: [Role!]
  groupIds: [UUID!]
  trainingIds: [UUID!]
  activityFrom: DateTime
  activityTo: DateTime
  sortBy: UserSortByInput = {field: NAME, direction: ASC}
  offset: Int
  before: String
  after: String
  first: Int
  last: Int
): UserSelectorConnection!

Mutations

createUser(sendInvite: Boolean = true, user: CreateUserInput!): CreateUser
updateUser(ref: String, id: UUID, user: UpdateUserInput!): UpdateUser
updateOrCreateUser(email: String, ref: String, sendInvite: Boolean, user: UpdateOrCreateUserInput!): UpdateOrCreateUser
archiveUsers(archive: Boolean!, ids: [UUID!]!): ArchiveUsers

CreateUserInput

UpdateUserInput additionally supports removeParticipantGroups and removeManagerGroups (both [UUID!]).

Notes

• Use updateOrCreateUser as the standard mutation for integrations — it prevents duplicate logic.
• archiveUsers is the designated way to deactivate users. There is no deleteUser mutation.
• The isActive field is deprecated and returns null. Use archived instead (archived: false = active, archived: true = inactive).
• The groups field is deprecated. Use participantGroups and managerGroups instead.
• When creating users with sendInvite: true, the user receives an email invitation to set their password and log in.
• The ref field is your anchor for synchronization. Always set it when creating users via integrations.