Group APIs

You can organize employees into manageable groups for easier administration. Zoho One lets you create two group types:

Departments: They can be used to mirror your organizational structure.
Collaboration Groups: They are the ad-hoc groups that can be created based on different needs.

End Points

POST

/orgs/{org_id}/groups

GET

/orgs/{org_id}/groups

PUT

/orgs/{org_id}/groups/{group_id}

GET

/orgs/{org_id}/groups/{group_id}

DELETE

/orgs/{org_id}/groups/{group_id}

Create a group

Creates a new group in the organization with the provided details.
OAuth Scope : ZohoOne.Groups.CREATE

Arguments

group_name

string

Name of the group.

group_description

string

Description of the group.

group_type

integer

Type of the group. 0 represents Collaboration Group and 1 represents Department.

members

array

Group members information.

Show Sub-Attributes

user_id

string

Represents the user id to whom you want to assign the group

member_role

integer

Indicates the group member role. 0 for member and 2 for moderator

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

Request Example

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://zohoapis.com/one/api/v2/orgs/987000000654321/groups")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/one/api/v2/orgs/987000000654321/groups"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/one/api/v2/orgs/987000000654321/groups",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/one/api/v2/orgs/987000000654321/groups", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request POST \
  --url https://zohoapis.com/one/api/v2/orgs/987000000654321/groups \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "groups": {
        "group_name": "Project Managers",
        "group_description": "This group is for the project managers in the organization",
        "group_type": 0,
        "members": [
            {
                "user_id": "2xxxxxxxxxxxxxxxx6",
                "member_role": 0
            }
        ]
    }
}

Response Example

{
    "status_code": 201,
    "resource_name": "groups",
    "message": "... //Successfully completed",
    "groups": {
        "group_id": ".....",
        "href": "....."
    }
}

{
    "status_code": 400,
    "error_code": "invalid_data",
    "message": "If a JSON parse error occurs during group creation"
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "no_permission",
    "message": "API is accessible to admins only"
}

{
    "status_code": 404,
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
}

{
    "status_code": 405,
    "error_code": "unsupported_operation",
    "message": "If current user is external user (or) if any inactive users in members list (or) If members list contains externalusers"
}

{
    "status_code": 409,
    "error_code": "resource_already_exists",
    "message": "If the given group_name already exists"
}

Get all groups in the organization

Fetches all the groups (collaboration group and department) in the organization with its details, such as name, ID, type, description, created, and modified time. This API by default lists only the collaboration groups available in the organization. To get departments and collaboration groups listed all together, you have to use the 'include' parameter in the API request.
OAuth Scope : ZohoOne.Groups.READ

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

Query Parameters

include

string

It helps to load the mentioned resource(s) info. Value is `departments`
Allowed values:
departments: Loads Groups along with Departments info

filter_department

string

It helps to filter the departments exists in this organisation
Allowed values:
departments: Loads Groups along with Departments info

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/one/api/v2/orgs/987000000654321/groups")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/one/api/v2/orgs/987000000654321/groups"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/one/api/v2/orgs/987000000654321/groups",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/one/api/v2/orgs/987000000654321/groups", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request GET \
  --url https://zohoapis.com/one/api/v2/orgs/987000000654321/groups \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

Response Example

{
    "status_code": 200,
    "resource_name": "groups",
    "groups": [
        {
            "group_id": "1xxxxxxx6",
            "created_time": "2024-xx-14T14:57:42.617+0530",
            "modified_time": "2025-01-22T15:41:32.487+0530",
            "group_name": "Project Managers",
            "group_type": 0,
            "group_description": "This group is for the project managers in the organization"
        },
        {...},
        {...}
    ]
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "no_permission",
    "message": "API is accessible to admins only"
}

{
    "status_code": 404,
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
}

{
    "status_code": 405,
    "error_code": "unsupported_operation",
    "message": "If current user is external user or MDM integration is not enabled for the requested filter"
}

Update a group's details

Updates the required group with the given details.
OAuth Scope : ZohoOne.Groups.UPDATE

Arguments

group_name

string

Name of the group.

group_description

string

Description of the group.

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

group_id

string

(Required)

ID of the group.

Request Example

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6")
  .put(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "PUT",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("PUT", "/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request PUT \
  --url https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "groups": {
        "group_name": "Project Managers",
        "group_description": "This group is for the project managers in the organization"
    }
}

Response Example

{
    "status_code": 200,
    "resource_name": "groups",
    "message": "... //Successfully completed",
    "groups": {
        "group_id": ".....",
        "href": "....."
    }
}

{
    "status_code": 400,
    "error_code": "invalid_user",
    "message": "If the given department_head user id is invalid"
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "no_permission",
    "message": "API is accessible to admins only"
}

{
    "status_code": 404,
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
}

{
    "status_code": 409,
    "error_code": "resource_already_exists",
    "message": "If the given group name is already exists"
}

Get specific group's details

Fetches the given group's details such as name, ID, type, description, created, and modified time.
OAuth Scope : ZohoOne.Groups.READ

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

group_id

string

(Required)

ID of the group.

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request GET \
  --url https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "status_code": 200,
    "resource_name": "groups",
    "groups": {
        "group_id": "1xxxxxxx6",
        "created_time": "2024-xx-14T14:57:42.617+0530",
        "modified_time": "2025-01-22T15:41:32.487+0530",
        "group_name": "Project Managers",
        "group_type": 0,
        "group_description": "This group is for the project managers in the organization"
    }
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "no_permission",
    "message": "API is accessible to admins only"
}

{
    "status_code": 404,
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
}

Delete a group

Deletes the given group.
OAuth Scope : ZohoOne.Groups.DELETE

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

group_id

string

(Required)

ID of the group.

Query Parameters

force

boolean

If set to true, the group will be deleted even if members are present; otherwise, an exception will be thrown. The default value is false

update_and_delete

boolean

If true, reassigns members to the department specified by replace_field_id before deleting; The default value is false

replace_field_id

string

The group_id of the replacement department to reassign members to when update_and_delete is true

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6")
  .delete(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6"
type: DELETE
headers: headers_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "DELETE",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("DELETE", "/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request DELETE \
  --url https://zohoapis.com/one/api/v2/orgs/987000000654321/groups/1xxxxxxx6 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

Response Example

{
    "status_code": 400,
    "error_code": "invalid_data",
    "message": "If replace_field_id target is not a department"
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "no_permission",
    "message": "API is accessible to admins only"
}

{
    "status_code": 404,
    "error_code": "invalid_identifier",
    "message": "If the group to be deleted is not found or is not a department"
}

{
    "status_code": 409,
    "error_code": "resource_in_use",
    "message": "If users are still in the group and force is not set to true"
}