Help Search

Edit on github

Create a group

Please note that only users with Admin role can create a group. To create a new group, make a POST request to /groups.json with the user data in request body.

POST /groups.json

{
  "name": "newgroup",
  "groups_users": [{
    "user_id": "<uuid_of_the_user_to_add>",
    "is_admin": true
  }, {
    "user_id": "<user2_uuid>",
    "is_admin": false
  }]
}

Parameters

The request body expects the following parameters

Parameter Description Required Validation Constraints
name Name for the new group Yes
  1. Valid utf8 string
  2. Must be unique
  3. Must not exceed 255 characters
groups_users An array of GroupsUser objects. Yes 1. At least one user must be provided
groups_users[0].user_id User id of the user to be added to the new group Yes
  1. A valid UUID
  2. A valid user id
groups_users[0].is_admin Passing “true” will make this user group admin Yes Boolean

Possible responses

Code Description
200 OK
The Group was created. The response body will contain the newly created group object
400 Bad Request
Some of the data validation failed.
403 Authentication Failure
The user making the request does not have the Admin role.

Examples

Validation errors

A successful request must pass all the validation checks. For example sending a blank request body will return:

{
    "header": {
        "id": "30777f73-5b4d-402b-9855-36331611b4bd",
        "status": "error",
        "servertime": 1554983343,
        "action": "5bd4ecae-da08-577d-ac32-ce7b13bd7b0f",
        "message": "Could not validate group data.",
        "url": "\/groups.json",
        "code": 400
    },
    "body": {
        "name": {
            "_required": "A name is required."
        }
    }
}

Similarly sending only a name

{
  "name": "New Group"
}

will still result in error:

{
    "header": {
        "id": "df12a670-b921-4db5-994f-22a84c36246a",
        "status": "error",
        "servertime": 1554983413,
        "action": "5bd4ecae-da08-577d-ac32-ce7b13bd7b0f",
        "message": "Could not validate group data.",
        "url": "\/groups.json",
        "code": 400
    },
    "body": {
        "groups_users": {
            "at_least_one_admin": "A group manager must be provided."
        }
    }
}

Last updated

This article was last updated on April 23rd, 2019.

For another perspective on the API you browse the OpenAPI 2.0 specifications using the dedicated API reference site (Swagger UI).

API Reference

You can also find the latest OpenAPI 2.0 specifications directly on the dedicated repository.

OpenAPI Specs repository