Groups

Available. Group list/create/get/update/delete and membership management shipped in the first LMS-539 write tranche. Deleting a group requires the admin scope; creating, updating, and editing membership require write. Groups created over the API are static — a dynamic group’s membership is computed from its rules and cannot be edited through this API. For identity-provider-driven provisioning, SCIM 2.0 group provisioning also remains available — see SCIM Provisioning.

Groups let you organize users for bulk enrollment, reporting, and access control. A user can belong to multiple groups.

The Group Object

{
  "id": "b4c3d2e1-5f6a-7890-bcde-f01234567890",
  "name": "Engineering Team",
  "description": "All engineering department employees",
  "member_count": 42,
  "created_at": "2026-01-20T09:00:00Z",
  "updated_at": "2026-04-10T14:30:00Z"
}

Endpoints

List Groups

GET /api/v1/groups

Returns a paginated list of all groups in the tenant.

Authentication required: read scope

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Default: `1`
`per_page`	integer	No	Default: `50`, max: `200`
`search`	string	No	Search on group name
`sort_by`	string	No	`name` or `created_at`. Default: `created_at`
`sort_order`	string	No	`asc` or `desc`. Default: `asc`

Example Request

curl "https://{your-subdomain}.embaylms.com/api/v1/groups" \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000"

Example Response

{
  "data": [
    {
      "id": "b4c3d2e1-5f6a-7890-bcde-f01234567890",
      "name": "Engineering Team",
      "description": "All engineering department employees",
      "member_count": 42,
      "created_at": "2026-01-20T09:00:00Z",
      "updated_at": "2026-04-10T14:30:00Z"
    },
    {
      "id": "c5d4e3f2-6a7b-8901-cdef-012345678901",
      "name": "New Hire Cohort — Q2 2026",
      "description": null,
      "member_count": 18,
      "created_at": "2026-04-01T08:00:00Z",
      "updated_at": "2026-04-01T08:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 12 },
  "error": null
}

Create Group

POST /api/v1/groups

Creates a new group.

Authentication required: write scope

Request Body

Field	Type	Required	Description
`name`	string	Yes	Group name. Must be unique within the tenant
`description`	string	No	Optional description

Example Request

curl -X POST https://{your-subdomain}.embaylms.com/api/v1/groups \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Operations Team",
    "description": "Field and operations department employees"
  }'

Example Response

{
  "data": {
    "id": "6f7a8b9c-0d1e-2345-abcd-345678901234",
    "name": "Operations Team",
    "description": "Field and operations department employees",
    "member_count": 0,
    "created_at": "2026-06-05T10:45:00Z",
    "updated_at": "2026-06-05T10:45:00Z"
  },
  "meta": null,
  "error": null
}

HTTP Status: 201 Created

Common Errors

HTTP Status	Description
`409`	A group with this name already exists in the tenant

Get Group

GET /api/v1/groups/{id}

Returns a single group by UUID.

Authentication required: read scope

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Group UUID

Example Request

curl "https://{your-subdomain}.embaylms.com/api/v1/groups/b4c3d2e1-5f6a-7890-bcde-f01234567890" \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000"

Example Response

Returns the full group object.

Common Errors

HTTP Status	Description
`404`	No group with this ID in the tenant

Update Group

PATCH /api/v1/groups/{id}

Updates the name or description of a group.

Authentication required: write scope

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Group UUID

Request Body

Field	Type	Required	Description
`name`	string	No	New group name
`description`	string or null	No	New description. Pass `null` to clear

Example Request

curl -X PATCH "https://{your-subdomain}.embaylms.com/api/v1/groups/b4c3d2e1-5f6a-7890-bcde-f01234567890" \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Software Engineering Team" }'

Example Response

Returns the updated group object.

Delete Group

DELETE /api/v1/groups/{id}

Deletes a group (soft delete — the group disappears from all lists and its name becomes available for reuse). Users in the group are not deleted; they remain in the tenant and lose the group association. Enrollments driven by this group are not affected.

Authentication required: admin scope

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Group UUID

Example Request

curl -X DELETE "https://{your-subdomain}.embaylms.com/api/v1/groups/b4c3d2e1-5f6a-7890-bcde-f01234567890" \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000"

HTTP Status: 204 No Content

List Group Members

GET /api/v1/groups/{id}/members

Returns a paginated list of users who are members of the group.

Authentication required: read scope

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Group UUID

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Default: `1`
`per_page`	integer	No	Default: `50`, max: `200`
`search`	string	No	Search on member name or email

Example Request

curl "https://{your-subdomain}.embaylms.com/api/v1/groups/b4c3d2e1-5f6a-7890-bcde-f01234567890/members" \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000"

Example Response

{
  "data": [
    {
      "id": "a3f2c1d0-4e5b-6789-abcd-ef0123456789",
      "email": "jane.doe@acme.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "role": "learner",
      "added_at": "2026-01-20T09:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 42 },
  "error": null
}

Add Members to Group

POST /api/v1/groups/{id}/members

Adds one or more users to a group. Users already in the group — and ids that do not match an active user in the tenant — are silently skipped and reported in the skipped count.

Authentication required: write scope

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Group UUID

Request Body

Field	Type	Required	Description
`user_ids`	UUID[]	Yes	Array of user UUIDs to add (max 500)

Example Request

curl -X POST "https://{your-subdomain}.embaylms.com/api/v1/groups/b4c3d2e1-5f6a-7890-bcde-f01234567890/members" \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "c5d4e3f2-6a7b-8901-cdef-012345678901",
      "1a2b3c4d-5e6f-7890-bcde-678901234567"
    ]
  }'

Example Response

{
  "data": {
    "added": 2,
    "skipped": 0
  },
  "meta": null,
  "error": null
}

HTTP Status: 200 OK

Common Errors

HTTP Status	Description
`400`	`user_ids` is empty or exceeds 500
`400`	`user_ids` missing, empty, over 500 items, or containing non-UUIDs
`422`	The group is dynamic — its membership is rule-computed and cannot be edited

Remove Members from Group

DELETE /api/v1/groups/{id}/members

Removes one or more users from a group. Users not in the group are silently skipped.

Authentication required: write scope

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Group UUID

Request Body

Field	Type	Required	Description
`user_ids`	UUID[]	Yes	Array of user UUIDs to remove (max 500)

Example Request

curl -X DELETE "https://{your-subdomain}.embaylms.com/api/v1/groups/b4c3d2e1-5f6a-7890-bcde-f01234567890/members" \
  -H "Authorization: Bearer ems_live_0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{ "user_ids": ["c5d4e3f2-6a7b-8901-cdef-012345678901"] }'

Example Response

{
  "data": {
    "removed": 1,
    "skipped": 0
  },
  "meta": null,
  "error": null
}

HTTP Status: 200 OK

Completions Reports (partial)