Skip to main content

Endpoint

Authentication

This endpoint requires authentication via API key. Include your API key in the X-API-Key header:

Request Body

The request body must be a JSON object with the following fields:

Required Fields

Optional Fields

Request Example

Response

Success Response

Status Code: 200 OK

Response Fields

Error Responses

400 Bad Request

Returned when the request is invalid - for example, a group name that already exists or an invalid user identifier. The detail reflects the underlying validation error.

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.

422 Unprocessable Entity

Returned when the request body fails validation - for example, an empty name.

500 Internal Server Error

Returned when the group could not be created due to a server error.

Notes

The new group is always created in the organization that owns the API key. The users_ids you supply are returned as member_user_ids in the response. Retrieve valid user identifiers via GET /users.

Use Cases

This endpoint is useful for:
  • Group provisioning - Programmatically create groups from an external system
  • Team setup - Seed a new group with its initial members in a single request
  • Access organization - Structure users into groups for downstream workflows