Groups API

1. Overview

The Groups API allows you to create, retrieve, list, update, and delete groups in SpeakUp. You can also manage group membership by adding or removing users.

Base Endpoint: {API_BASE_URL}/scim/v2/Groups

---

2. Authentication

All requests require the Authorization header with a bearer token. See the SpeakUp SCIM Overview for authentication details

---

3. Response Structure 

---

4. Create a Group

Create a new group in SpeakUp. The displayName is required and must be unique. You may optionally provide externalId and initial members.

HTTP Method: POST
Endpoint: /scim/v2/Groups

4.1 Request (minimal)

4.2 Request (with externalId and members)

4.3 Response (201 Created) 

4.4 Common Errors

400 Bad Request (missing displayName):

409 Conflict (displayName already exists):

400 Bad Request (one or more member users not found or not eligible):

---

5. Get a Specific Group

Retrieve details of a single group by ID.

HTTP Method: GET
Endpoint: /scim/v2/Groups/{id}

5.1 Request

5.2 Response (200 OK)

5.4 Request

5.5 Response (200 OK)

5.6 Error (404 Not Found)

---

6. List All Groups

Retrieve all groups with optional filtering and pagination.

HTTP Method: GET
Endpoint: /scim/v2/Groups

6.1 Query Parameters

6.3 Request (with pagination)

6.4 Request (with filter)

6.5 Response (200 OK)

6.6 Filter Examples

---

7. Add Members to a Group

Add one or more users to an existing group.

HTTP Method: PATCH
Endpoint: /scim/v2/Groups/{id}

7.1 Request (single member)

Returns the full group in SCIM format (including updated members and meta.lastModified).

7.4 Common Errors

404 Not Found (group does not exist):

400 Bad Request (user does not exist or is not eligible):

---

8. Remove Members from a Group

Remove one or more users from a group.

HTTP Method: PATCH
Endpoint: /scim/v2/Groups/{id}

8.1 Request (single member)

 8.2 Request (multiple members)

Returns the full group in SCIM format with updated members and meta.lastModified.

---

9. Update Group (PUT)

Update a group with full replacement. All writable attributes should be sent; omitted attributes are effectively cleared. Members not included in the payload are removed from the group.

HTTP Method: PUT
Endpoint: /scim/v2/Groups/{id}

9.1 Request

9.2 Response (200 OK)

Returns the full group in SCIM format. Members will include value, display, and $ref.

9.3 Error (409 Conflict)

---

10. Delete a Group

Delete a group. This removes the group but does not delete the users who were members.

HTTP Method: DELETE
Endpoint: /scim/v2/Groups/{id}

10.1 Request

10.2 Response (204 No Content)

No response body.

---

11. Common Status Codes

---

12. SpeakUp ↔ SCIM Attribute Mapping (Groups)