---
title: "Groups"
url: "https://earlyaccess.developers.bynder.com/apis/groups-1/versions/8b5e3751-b1f6-4df8-9f5d-f494f76062f0"
---

# Groups

OpenAPI specification document.

```json
{"components":{"responses":{"Forbidden":{"description":"The authenticated user does not have the **GROUPMANAGEMENT** security role."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}},"description":"Group not found."},"Unauthorized":{"description":"Missing or invalid authentication. The response body is empty."}},"schemas":{"ErrorResponse":{"properties":{"detail":{"properties":{"error":{"description":"Human-readable description of the error.","type":"string"}},"type":"object"}},"type":"object"},"Group":{"example":{"description":"Everyone in the marketing department","id":"0397e4bd-33fe-4b8f-a51d-4c2f1d9b6c1a","name":"Marketing","user_count":12},"properties":{"description":{"type":["string","null"]},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"user_count":{"description":"Number of members in the group.","type":"integer"}},"type":"object"},"GroupMembersInput":{"properties":{"user_ids":{"description":"IDs of the users to add or remove. An empty list is a no-op.","items":{"format":"uuid","type":"string"},"type":"array"}},"required":["user_ids"],"type":"object"},"GroupMembersResult":{"properties":{"user_count":{"description":"Updated number of members in the group after the operation.","type":"integer"}},"type":"object"},"NotFoundResponse":{"properties":{"detail":{"example":"Not Found","type":"string"}},"type":"object"}},"securitySchemes":{"OAuth2":{"flows":{"authorizationCode":{"authorizationUrl":"https://{your-auth-url}","scopes":{"GROUPMANAGEMENT":"Grants permission to manage groups`"},"tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token"},"clientCredentials":{"scopes":{"GROUPMANAGEMENT":"Grants permission to manage groups"},"tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token"}},"type":"oauth2"},"permanentToken":{"in":"header","name":"Authorization","type":"apiKey"}}},"info":{"title":"Groups","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/1/groups":{"get":{"description":"Returns a paginated list of groups with member count.\n\nRequires the **GROUPMANAGEMENT** security role.\n","operationId":"listGroups","parameters":[{"description":"Filter groups by matching name.","in":"query","name":"search_term","required":false,"schema":{"type":"string"}},{"description":"Filter by specific group IDs (hyphens in the UUIDs are optional).","in":"query","name":"ids[]","required":false,"schema":{"items":{"format":"uuid","type":"string"},"type":"array"}},{"description":"Sort field and direction. Prefix with `-` for descending order (e.g. `-name`).","in":"query","name":"sort","required":false,"schema":{"default":"name","enum":["name","description","-name","-description"],"type":"string"}},{"description":"Page number (1-based).","in":"query","name":"start","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Number of results per page.","in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":1000,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Group"},"type":"array"},"metadata":{"properties":{"nextPage":{"description":"Relative URL of the next page, or null if on the last page.","type":["string","null"]},"prevPage":{"description":"Relative URL of the previous page, or null if on the first page.","type":["string","null"]}},"type":"object"}},"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unsupported `sort` value."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Validation error (e.g. `start` less than 1, `limit` outside 1–1000, malformed group ID in `ids[]`)."}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"List groups","tags":["Groups (Preferred)"]},"post":{"description":"Creates a new group.\n\nRequires the **GROUPMANAGEMENT** security role.\n","operationId":"createGroup","requestBody":{"content":{"application/json":{"schema":{"properties":{"description":{"description":"Optional description of the group.","type":["string","null"]},"name":{"description":"Name of the group. Must be unique within the account. Must be a string (numbers are not coerced).","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}},"description":"Group created successfully."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A group with this name already exists."},"422":{"description":"Validation error (e.g. `name` is missing or not a string)."}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"Create a group","tags":["Groups (Preferred)"]}},"/api/1/groups/{groupId}":{"delete":{"description":"Deletes a group and removes all its members from it.\n\nRequires the **GROUPMANAGEMENT** security role.\n","operationId":"deleteGroup","parameters":[{"description":"ID of the group to delete (hyphens optional).","in":"path","name":"groupId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Group deleted successfully. No content is returned."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error (malformed group ID)."}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"Delete a group","tags":["Groups (Preferred)"]},"get":{"description":"Returns a single group by its ID, including member count.\n\nRequires the **GROUPMANAGEMENT** security role.\n","operationId":"getGroup","parameters":[{"description":"ID of the group (hyphens optional).","in":"path","name":"groupId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}},"description":"Successful response"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error (malformed group ID)."}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"Get group by ID","tags":["Groups (Preferred)"]},"patch":{"description":"Updates the name and/or description of an existing group.\n\nAt least one field must be provided. Only the fields included in the request body are updated\n(partial update semantics).\n\nRequires the **GROUPMANAGEMENT** security role.\n","operationId":"updateGroup","parameters":[{"description":"ID of the group to update (hyphens optional).","in":"path","name":"groupId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"minProperties":1,"properties":{"description":{"description":"New description for the group. Pass `null` to clear it.","type":["string","null"]},"name":{"description":"New name for the group. Must be unique within the account.","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}},"description":"Group updated successfully."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A group with the requested name already exists."},"422":{"description":"Validation error (e.g. empty request body, malformed group ID, or `name` is not a string)."}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"Update a group","tags":["Groups (Preferred)"]}},"/api/1/groups/{groupId}/add-users":{"post":{"description":"Adds one or more users to the specified group. Pass a single-element array to add one user.\n\nUsers that are already members of the group are silently ignored (the operation is idempotent).\nAn empty `user_ids` array is accepted and is a no-op.\n\nRequires the **GROUPMANAGEMENT** security role.\n","operationId":"addUsersToGroup","parameters":[{"description":"ID of the group (hyphens optional).","in":"path","name":"groupId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupMembersInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupMembersResult"}}},"description":"Users added successfully."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"One or more user IDs do not exist in the account."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error (e.g. missing `user_ids` field or malformed UUID)."}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"Add users to a group","tags":["Groups (Preferred)"]}},"/api/1/groups/{groupId}/remove-users":{"post":{"description":"Removes one or more users from the specified group. Pass a single-element array to remove one user.\n\nUsers not currently in the group are silently ignored (the operation is idempotent).\nAn empty `user_ids` array is accepted and is a no-op.\n\nRequires the **GROUPMANAGEMENT** security role.\n","operationId":"removeUsersFromGroup","parameters":[{"description":"ID of the group (hyphens optional).","in":"path","name":"groupId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupMembersInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupMembersResult"}}},"description":"Users removed successfully."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"One or more user IDs do not exist in the account."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error (e.g. missing `user_ids` field or malformed UUID)."}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"Remove users from a group","tags":["Groups (Preferred)"]}},"/api/groups/list/":{"get":{"description":"Requires the **GROUPMANAGEMENT** security role.","operationId":"retrieveGroupsLegacy","parameters":[{"description":"Search on matching group names.","in":"query","name":"search_term","required":false,"schema":{"type":"string"}},{"description":"What page of results to return.","in":"query","name":"page","required":false,"schema":{"default":1,"type":"integer"}},{"description":"Maximum results to return. If limit is not provided the first 20 results will be returned.","in":"query","name":"limit","required":false,"schema":{"default":20,"type":"integer"}},{"description":"Order of the returned list of groups.","in":"query","name":"sort_order","required":false,"schema":{"enum":["asc","desc"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"}}},"description":"Successful response"}},"security":[{"permanentToken":["GROUPMANAGEMENT"]},{"OAuth2":["GROUPMANAGEMENT"]}],"summary":"Retrieve groups","tags":["Groups (Legacy)"]}}},"servers":[{"url":"https://{your-bynder-domain}/"}],"tags":[{"name":"Groups (Preferred)"},{"name":"Groups (Legacy)"}]}
```