Skip to main content

Manage groups

This example demonstrates how to manage groups in ONLYOFFICE DocSpace using the API. It covers creating, retrieving, updating, and deleting groups through API requests. The script follows a logical sequence to demonstrate how to interact with the group management system in a real-world scenario.

Before you start​

  1. Replace https://yourportal.onlyoffice.com and YOUR_API_KEY with your actual DocSpace portal URL and API key. Ensure you have the necessary data and permissions to perform migration operations.
  2. Before you can make requests to the API, you need to authenticate. Check out the Personal access tokens page to learn how to obtain and use access tokens.
Full example
// Set API base URL
const API_HOST = 'https://yourportal.onlyoffice.com';
const API_KEY = 'your_api_key';

// Headers with API key for authentication
const HEADERS = {
  Accept: 'application/json',
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

// Step 1: Create a new group
async function createGroup(groupName, managerId, memberIds) {
  const url = `${API_HOST}/api/2.0/group`;
  const data = { groupName, groupManager: managerId, members: memberIds };

  const res = await fetch(url, { method: 'POST', headers: HEADERS, body: JSON.stringify(data) });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group creation failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  const groupId = json?.response?.id;
  console.log('Group created successfully:', groupId);
  return groupId;
}

// Step 2: Retrieve group by ID
async function getGroupById(groupId) {
  const url = `${API_HOST}/api/2.0/group/${groupId}`;
  const res = await fetch(url, { method: 'GET', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group retrieval failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  console.log(json);
  return json;
}

// Step 3: Update an existing group
async function updateGroup(groupId, newGroupName) {
  const url = `${API_HOST}/api/2.0/group/${groupId}`;
  const data = { groupName: newGroupName };

  const res = await fetch(url, { method: 'PUT', headers: HEADERS, body: JSON.stringify(data) });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group update failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  const id = json?.response?.id;
  console.log('Group updated successfully:', id);
  return id;
}

// Step 4: Delete a group
async function deleteGroup(groupId) {
  const url = `${API_HOST}/api/2.0/group/${groupId}`;
  const res = await fetch(url, { method: 'DELETE', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group deletion failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  console.log(res.status);
  return res.status;
}

// Run sequence
(async () => {
  try {
    const group_name = 'New Group'; // Replace with actual group name
    const manager_id = '10001';     // Replace with actual manager ID
    const member_ids = ['10001', '10002']; // Replace with actual member IDs

    const groupId = await createGroup(group_name, manager_id, member_ids);
    await getGroupById(groupId);
    await updateGroup(groupId, 'Updated Group Name');
    await deleteGroup(groupId);
  } catch (err) {
    console.error(err.message);
  }
})();

Step 1: Create a group​

A POST request is sent to /api/2.0/group with:

  • groupName: A new group name.
  • groupManager: The user ID of the group manager.
  • members: A list of user IDs to be added to the group.

The API returns a group ID, which is required for further operations.

async function createGroup(groupName, managerId, memberIds) {
  const url = `${API_HOST}/api/2.0/group`;
  const data = { groupName, groupManager: managerId, members: memberIds };

  const res = await fetch(url, { method: 'POST', headers: HEADERS, body: JSON.stringify(data) });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group creation failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  const groupId = json?.response?.id;
  console.log('Group created successfully:', groupId);
  return groupId;
}

Step 2: Retrieve a group by ID​

A GET request is sent to /api/2.0/group/:id to fetch group details.

The response includes the group's information.

This step ensures that the group exists before making any updates or deletions.

async function getGroupById(groupId) {
  const url = `${API_HOST}/api/2.0/group/${groupId}`;
  const res = await fetch(url, { method: 'GET', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group retrieval failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  console.log(json);
  return json;
}

Step 3: Update a group​

A PUT request is sent to /api/2.0/group/:id.

The request updates the group details and returns a confirmation if successful.

This step simulates renaming or modifying the existing group's properties.

async function updateGroup(groupId, newGroupName) {
  const url = `${API_HOST}/api/2.0/group/${groupId}`;
  const data = { groupName: newGroupName };

  const res = await fetch(url, { method: 'PUT', headers: HEADERS, body: JSON.stringify(data) });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group update failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  const id = json?.response?.id;
  console.log('Group updated successfully:', id);
  return id;
}

Step 4: Delete a group​

A DELETE request is sent to /api/2.0/group/:id.

The response confirms the deletion, ensuring that the group no longer appears in the list of groups.

This step is crucial for cleaning up unused or test data.

async function deleteGroup(groupId) {
  const url = `${API_HOST}/api/2.0/group/${groupId}`;
  const res = await fetch(url, { method: 'DELETE', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Group deletion failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  console.log(res.status);
  return res.status;
}