---
title: "List User Groups"
method: GET
path: "/api/v1/user-groups"
tags: ["User Groups"]
---

# List User Groups

`GET /api/v1/user-groups`

Get a list of user groups

## Query parameters

- `page` integer — The page number to fetch.
- `size` integer — The number of items per page.
- `skip_count` boolean — Whether to skip counting the total number of items.
- `states` UserGroupState[]
- `user_group_ids` string[]
- `user_ids` string[]
- `modified_by` string[]
- `name` string
- `search` string
- `exclude_user_group_ids` string[] — The group IDs to exclude.
- `sort_by` UserGroupSortableFields[]

## Response `200`

Successful Response

- ListUserGroupsResponse
  - `total` integer, required
  - `page` integer, required
  - `size` integer, required
  - `user_groups` UserGroup[], required
    - `id` string, uuid, required — The unique identifier of the object in the Fordefi platform.
    - `created_at` string, date-time, required — The date and time when the object was created.
    - `modified_at` string, date-time, required — The date and time when the object was last modified. Any change to any field of the resource is considered a modification.
    - `name` string, required — The name of the user group.
    - `users_count` integer, required — The number of users in the group.
    - `admins_count` integer, required — The number of admins in the group.
    - `state` 'active' | 'deleted', required — Represents a user group state in the Fordefi platform
    - `modified_by` union, required — Represents a reference to a user in the Fordefi platform
      - PersonRef
        - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
        - `user_type` 'person', required — The type of user. Can be a person, or (in programmatic scenarios) an API user or API Signer.
        - `name` string — The name of the user.
        - `email` string, required — The email of the user.
        - `state` 'active' | 'onboarding_pending_code_generation' | 'onboarding_pending_activation' | 'reset_device_pending_code_generation' | 'reset_device_pending_activation' | 'pending_approval' | 'deleted', required
        - `role` 'admin' | 'trader' | 'viewer', required
      - ApiUserRef
        - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
        - `user_type` 'api_user', required — The type of the user.
        - `name` string, required — The name of the user.
        - `state` 'active' | 'deleted', required — The state of the user.
        - `role` 'admin' | 'trader' | 'viewer', required
      - ApiSignerRef
        - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
        - `user_type` 'api_signer', required — The type of the user.
        - `name` string, required — The name of the user.
        - `state` 'active' | 'onboarding_pending_code_generation' | 'onboarding_pending_activation' | 'deleted', required — The state of the user.
      - EndUserRef
        - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
        - `user_type` 'end_user', required — The type of the user.
        - `external_id` string, required — External id of the user.
        - `state` 'active' | 'deleted', required — The state of the user.
      - SystemUserRef
        - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
        - `user_type` 'system', required — The type of the user.
        - `name` string, required — The name is Fordefi CARE
    - `proposed_change` UserGroupChangeRequest — Represents a user group change proposal in the Fordefi platform
      - `id` string, uuid, required — The ID of the change proposal.
      - `created_at` string, date-time, required — The time the change proposal was created.
      - `created_by` union, required — Represents a reference to a user in the Fordefi platform
        - PersonRef
          - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
          - `user_type` 'person', required — The type of user. Can be a person, or (in programmatic scenarios) an API user or API Signer.
          - `name` string — The name of the user.
          - `email` string, required — The email of the user.
          - `state` 'active' | 'onboarding_pending_code_generation' | 'onboarding_pending_activation' | 'reset_device_pending_code_generation' | 'reset_device_pending_activation' | 'pending_approval' | 'deleted', required
          - `role` 'admin' | 'trader' | 'viewer', required
        - ApiUserRef
          - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
          - `user_type` 'api_user', required — The type of the user.
          - `name` string, required — The name of the user.
          - `state` 'active' | 'deleted', required — The state of the user.
          - `role` 'admin' | 'trader' | 'viewer', required
        - ApiSignerRef
          - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
          - `user_type` 'api_signer', required — The type of the user.
          - `name` string, required — The name of the user.
          - `state` 'active' | 'onboarding_pending_code_generation' | 'onboarding_pending_activation' | 'deleted', required — The state of the user.
        - EndUserRef
          - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
          - `user_type` 'end_user', required — The type of the user.
          - `external_id` string, required — External id of the user.
          - `state` 'active' | 'deleted', required — The state of the user.
        - SystemUserRef
          - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
          - `user_type` 'system', required — The type of the user.
          - `name` string, required — The name is Fordefi CARE
      - `new_name` string — The new name of the group if it is changed.
      - `added_users` GroupUserRef[] — The users added to the group.
        - union — Represents a reference to a group user in the Fordefi platform
          - PersonRef
            - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
            - `user_type` 'person', required — The type of user. Can be a person, or (in programmatic scenarios) an API user or API Signer.
            - `name` string — The name of the user.
            - `email` string, required — The email of the user.
            - `state` 'active' | 'onboarding_pending_code_generation' | 'onboarding_pending_activation' | 'reset_device_pending_code_generation' | 'reset_device_pending_activation' | 'pending_approval' | 'deleted', required
            - `role` 'admin' | 'trader' | 'viewer', required
          - ApiUserRef
            - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
            - `user_type` 'api_user', required — The type of the user.
            - `name` string, required — The name of the user.
            - `state` 'active' | 'deleted', required — The state of the user.
            - `role` 'admin' | 'trader' | 'viewer', required
      - `removed_users` GroupUserRef[] — The users removed from the group.
        - union — Represents a reference to a group user in the Fordefi platform
          - PersonRef
            - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
            - `user_type` 'person', required — The type of user. Can be a person, or (in programmatic scenarios) an API user or API Signer.
            - `name` string — The name of the user.
            - `email` string, required — The email of the user.
            - `state` 'active' | 'onboarding_pending_code_generation' | 'onboarding_pending_activation' | 'reset_device_pending_code_generation' | 'reset_device_pending_activation' | 'pending_approval' | 'deleted', required
            - `role` 'admin' | 'trader' | 'viewer', required
          - ApiUserRef
            - `id` string, uuid, required — The unique identifier of the user in the Fordefi platform.
            - `user_type` 'api_user', required — The type of the user.
            - `name` string, required — The name of the user.
            - `state` 'active' | 'deleted', required — The state of the user.
            - `role` 'admin' | 'trader' | 'viewer', required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized User
- `403` — Forbidden User
- `408` — Request Timeout
- `422` — Validation Error
- `429` — Rate Limit Exceeded
- `500` — Unexpected Error

---

[API](https://skmtc.net/fordefi/apis/fordefi-api.md) · [All operations](https://skmtc.net/fordefi/apis/fordefi-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fordefi/fordefi-api/versions/8014fd69ea17/schema)