Documentation (2024.2 Enterprise)

# Group

Group is a collection of Users. Groups can be linked to Projects by assigning them a project role, which has the same effect as assigning a role for each group member individually.

- Attributes
- Searchable attributes
- Child objects
- Operations
  - `GET /groups`
  - `GET /groups/:id`
  - `POST /groups`
  - `PUT /groups/:id`
  - `DELETE /groups/:id`

## Attributes

### id

URL-friendly identifier for the group.

- Type: `string`
- Immutable: `true`
- Unique: `true`
- Required: `true`
- Minimum length: `2`
- Maximum length: `100`
- Allowed characters: `a-z`, `A-Z`, `0-9`, `-`, `_`

### name

Human-readable name for the group.

- Type: `string`
- Unique: `true`
- Required: `true`
- Minimum length: `2`
- Maximum length: `100`

### description

A free-form description of the group.

- Type: `string`
- Default: `""`
- Maximum length: `512`

### visibility

Public groups are visible to everyone in the company and anyone can take them into use in their projects. Private groups are only visible to members of the group and only they can manage project roles for the group.

- Type: `string`
- Default: `public`
- Allowed values: `public`, `private`

### source

The identifier of the external source where the group is synchronized from.

- Type: `string`
- Default: `""`
- Maximum length: `500`

### linked

A group in considered as linked when its source has a value. This field is automatically updated.

- Type: `boolean`
- Default: `false`

## Searchable attributes

Groups can be searched by their `id` and `name` attributes. See the search documentation for instructions how to do this.

## Child objects

The following child objects can be attached to the groups returned, to eliminate the need for requesting them separately:

Object | Attribute
--- | ---
User | `users`

For example to get all the group's users, attach `include=users` to your GET request.

See the child object API documentation for a description of the possible operations.

## Operations

### GET /groups

Returns all the groups in the company, with optional limit and offset parameters, as a metadata-results object.

### GET /groups/:id

Returns specific group object.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/groups/designers

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-11-27T15:04:40Z",
      "id": "designers",
      "created_at": "2013-11-18T12:22:15Z",
      "updated_at": "2013-11-27T11:43:04Z",
      "name": "Designers",
      "description": "All designers in our company",
      "visibility": "public",
      "source": "I_DESIGNERS",
      "linked": true
    }

### POST /groups

Creates a new group to the company. Returns the created group object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "id": "devs", "name": "Developers" }' \
      https://helixteamhub.cloud/api/groups

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2013-11-27T15:24:49Z",
      "id": "devs",
      "created_at": "2013-11-27T15:24:49Z",
      "updated_at": "2013-11-27T15:24:49Z",
      "name": "Developers",
      "description": "",
      "visibility": "public",
      "source": "",
      "linked": false
    }

### PUT /groups/:id

Updates a group. Returns the updated group object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "source": "I_DEVS" }' \
      https://helixteamhub.cloud/api/groups/devs

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-11-27T15:25:51Z",
      "id": "devs",
      "created_at": "2013-11-27T15:24:49Z",
      "updated_at": "2013-11-27T15:25:51Z",
      "name": "Developers",
      "description": "",
      "visibility": "public",
      "source": "I_DEVS",
      "linked": true
    }

### DELETE /groups/:id

Deletes a group. Returns the deleted group object.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/groups/devs

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-11-27T15:27:28Z",
      "id": "devs",
      "created_at": "2013-11-27T15:24:49Z",
      "updated_at": "2013-11-27T15:25:51Z",
      "name": "Developers",
      "description": "",
      "visibility": "public",
      "source": "I_DEVS",
      "linked": true
    }

Your search for returned results

Your search for returned results