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
}