Skip to content

Groups API

Groups are used to apply the same callflow or actions to a number of users simultaneously. Use the Groups API to manage the groups in your account.

API calls

Click on each call to view the endpoint, method, and request example.

Parameters

The table shows the possible parameters available for groups requests.

Key Description Type Options/Min/Max/Default
name Required. A friendly name for the group. string (1..128)
endpoints Required. Endpoints included into group. object
flags.[] Specific flags on the group. string
flags Flags set by external applications. array
music_on_hold.media_id The ID of a media object that should be used as music on hold. string (0..128)
music_on_hold The music on hold parameters. object

Get groups

Returns a list of groups in the account.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/groups

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/groups

Response

  {
      "data": [
          {
              "id": "18ccfd6cea456cbdd38133e5aa726ec4",
              "name": "Group Name",
              "features": [],
              "endpoints": 2
          }
      ],
      "status": "success"
  }

Get all groups containing a user

Returns a list of groups that contain a specific user.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/groups

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/groups

Response

{
    "data": [
        {
            "id": "18ccfd6cea456cbdd38133e5aa726ec4",
            "name": "Group Name",
            "features": [],
            "endpoints": 2
        }
    ],
    "status": "success"
}

Create a group for a given account

Creates a group for the account.

Method and endpoint

  PUT /v2/accounts/{ACCOUNT_ID}/groups

Request

    curl -v -X PUT \
        -H "X-Auth-Token: {AUTH_TOKEN}" \
        -d '{
                "data": {
                    "music_on_hold": {},
                    "name": "Test group",
                    "endpoints": {
                        "df9274b450ea6795cdb381055c3f9b45": {
                            "type": "user",
                            "weight": 1
                        },
                        "dd03d7442a4bec5c092ea6a0e6d579ef": {
                            "type": "device",
                            "weight": 2
                        }
                    }
                },
                "verb": "PUT"
            }' \
        http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/groups

Response

  {
      "data": {
          "music_on_hold": {},
          "name": "Test group",
          "endpoints": {
              "df9274b450ea6795cdb381055c3f9b45": {
                  "type": "user",
                  "weight": 1
              },
              "dd03d7442a4bec5c092ea6a0e6d579ef": {
                  "type": "device",
                  "weight": 2
              }
          },
          "id": "1743724cd775bf6994380dbc79c1af09"
      },
      "status": "success"
  }

Remove a group

Removes a group from the account.

Method and endpoint

  DELETE /v2/accounts/{ACCOUNT_ID}/groups/{GROUP_ID}

Request

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/groups/{GROUP_ID}

Response

  {
      "data": {
          "music_on_hold": {},
          "name": "Test group 2",
          "id": "1743724cd775bf6994380dbc79c1af09",
          "endpoints": {
              "df9274b450ea6795cdb381055c3f9b45": {
                  "type": "user",
                  "weight": 1
              },
              "dd03d7442a4bec5c092ea6a0e6d579ef": {
                  "type": "device",
                  "weight": 2
              }
          }
      },
      "status": "success"
  }

Get a group for a given account

Returns details for a specific group.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/groups/{GROUP_ID}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/groups/{GROUP_ID}

Response

{
    "data": {
        "music_on_hold": {},
        "name": "Test group",
        "endpoints": {
            "df9274b450ea6795cdb381055c3f9b45": {
                "type": "user",
                "weight": 1
            },
            "dd03d7442a4bec5c092ea6a0e6d579ef": {
                "type": "device",
                "weight": 2
            }
        },
        "ui_metadata": {
            "ui": "kazoo-ui"
        },
        "id": "1743724cd775bf6994380dbc79c1af09"
    },
    "status": "success"
}

Update a group for a given account

Updates a group for a specific account.

Method and endpoints

POST /v2/accounts/{ACCOUNT_ID}/groups/{GROUP_ID}

PATCH /v2/accounts/{ACCOUNT_ID}/groups/{GROUP_ID}

Request

  curl -v -X POST \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      -d '{
          "data": {
              "music_on_hold": {},
              "name": "Test group 2",
              "id": "1743724cd775bf6994380dbc79c1af09",
              "endpoints": {
                  "df9274b450ea6795cdb381055c3f9b45": {
                      "type": "user",
                      "weight": 1
                  },
                  "dd03d7442a4bec5c092ea6a0e6d579ef": {
                      "type": "device",
                      "weight": 2
                  }
              }
          },
          "verb": "POST"
      }' \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/groups/{GROUP_ID}

Response

  {
      "data": {
          "music_on_hold": {},
          "name": "Test group 2",
          "endpoints": {
              "df9274b450ea6795cdb381055c3f9b45": {
                  "type": "user",
                  "weight": 1
              },
              "dd03d7442a4bec5c092ea6a0e6d579ef": {
                  "type": "device",
                  "weight": 2
              }
          },
          "ui_metadata": {
              "ui": "kazoo-ui"
          },
          "id": "1743724cd775bf6994380dbc79c1af09"
      },
      "status": "success"
  }