2. Nested Folders and Document Organization

Nested Folders and Document Organization

This scenario demonstrates how to create hierarchical folder structures and organize existing documents within them. Nested folders provide a powerful way to categorize and manage documents according to your organizational needs.

Key features:

Create hierarchical folder structures with parent-child relationships
Organize existing documents by moving them into specific folders
Implement logical document categorization for improved findability

Prerequisites

Before working with nested folders and document organization, you need:

A valid authentication token (see the "Authentication & Security" section for details)
Existing documents that you want to organize
A clear organizational structure for your document hierarchy

Step 1 - Create root folder

This endpoint creates a new root-level folder that will serve as the parent for nested folders. Root folders are the top level of your folder hierarchy.

The name parameter defines the display name of the folder
The isShared parameter set to false creates a private folder visible only to you
The parentFolderId parameter set to null places the folder at the root level

Private folders (isShared: false) are only accessible to the creator and users explicitly granted access. This is useful for personal document organization or sensitive content.

Endpoint

CODE

POST /folders

Request

JSON

POST /folders?token=uJhSlBpdKhwju77ab4lFv8UdQWdELtjnjSA1IQEGpqvjRum1AOsIGneyrjOFxWPC

Content-Type: application/json

{
  "name": "Completed Documents",  //Display name of the root folder
  "isShared": false,  //Private folder (false) vs. shared folder (true)
  "parentFolderId": null  //null indicates this is a root-level folder
}

Response

JSON

{
  "id": "5d821888-596f-4b3f-8076-7404d7488d99",
  "success": true
}

The response contains the following important properties:

rootFolderId - Located at id in the response.
- The unique identifier for the newly created root folder. This ID will be used as the parent for nested folders.
- Example value: 5d821888-596f-4b3f-8076-7404d7488d99

The root folder has been successfully created at the top level of the folder hierarchy.

The response includes the folder ID which will be used to create nested folders within it
The folder is created with private access settings, making it visible only to you
This folder will serve as the parent for more specific nested folders

Step 2 - Create nested folder

This endpoint creates a nested folder within the previously created root folder. Nested folders allow you to create a hierarchical structure for more granular document organization.

The name parameter defines the display name of the nested folder
The isShared parameter determines the access control settings
The parentFolderId parameter specifies which folder this new folder belongs to

Nested folders inherit access control settings from their parent folders. A private folder cannot contain shared subfolders, and vice versa, to maintain consistent access control.

Endpoint

CODE

POST /folders

Request

JSON

POST /folders?token=uJhSlBpdKhwju77ab4lFv8UdQWdELtjnjSA1IQEGpqvjRum1AOsIGneyrjOFxWPC

Content-Type: application/json

{
  "name": "Invoices",  //Display name of the nested folder
  "isShared": false,  //Access control setting (must match parent folder)
  "parentFolderId": "5d821888-596f-4b3f-8076-7404d7488d99"  //ID of the parent folder where this folder will be created
}

Response

JSON

{
  "id": "38b67d7d-7fde-48f4-b0b9-e584b6555f16",
  "success": true
}

The response contains the following important properties:

nestedFolderId - Located at id in the response.
- The unique identifier for the newly created nested folder. Use this ID to place documents in this folder.
- Example value: 38b67d7d-7fde-48f4-b0b9-e584b6555f16

The nested folder has been successfully created within the parent folder.

The response includes the folder ID which will be used to place documents in this folder
The folder inherits access control settings from its parent folder
The folder hierarchy now has two levels: the root "Completed Documents" folder and the nested "Invoices" folder

You can create multiple nested folders within the same parent to organize different types of documents.

Step 3 - Move documents into folder

This endpoint moves existing documents into a specific folder. Moving documents helps organize your content.

The docs array contains the IDs of documents you want to move
The folderId parameter specifies the destination folder

Endpoint

CODE

PUT /folders/move

Request

JSON

PUT /folders/move?token=uJhSlBpdKhwju77ab4lFv8UdQWdELtjnjSA1IQEGpqvjRum1AOsIGneyrjOFxWPC

Content-Type: application/json

{
  "docs": [
    {
      "id": "f54006d2-0dbd-4e65-b3b9-d58e4170a3ab"  //Document ID that you want to move
    }
  ],
  "folderId": "38b67d7d-7fde-48f4-b0b9-e584b6555f16"  //Destination folder ID where documents will be moved
}

Response

JSON

{
  "errors": false,
  "count": 1,
  "items": []
}

The document has been successfully moved to the specified folder.

The document is now located in the nested "Invoices" folder
The document will now appear in the folder's contents when browsing or searching

You can move multiple documents at once by adding more document IDs to the docs array. This is useful for bulk organization of related documents.

Nested Folders and Document Organization Summary

You have successfully learned how to create hierarchical folder structures and organize documents within them in the Circularo system.

Key Concepts

Folder Hierarchy: Create multi-level folder structures for logical document organization
Nested Folders: Place folders within other folders to create a tree-like structure
Document Movement: Relocate existing documents into appropriate folders

Best Practices

Design your folder structure before implementation to ensure it meets your organizational needs
Use consistent naming conventions for folders to make navigation intuitive
Regularly review and reorganize your folder structure as your document collection grows

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT

// Nested folders and document organization example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key
const DOCUMENT_ID = "YOUR_DOCUMENT_ID"; // ID of an existing document to organize

try {
    // Step 1: Create a root folder
    const createRootFolderResponse = await fetch(`${URL}${API_PATH}/folders?token=${TOKEN}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            name: "Completed Documents",
            isShared: false,
            parentFolderId: null
        })
    });
    if (!createRootFolderResponse.ok) {
        throw new Error(`Root folder creation failed: ${createRootFolderResponse.status} ${createRootFolderResponse.statusText}`);
    }

    const rootFolderData = await createRootFolderResponse.json();
    const rootFolderId = rootFolderData.id;
    console.log(`Root folder created with ID: ${rootFolderId}`);

    // Step 2: Create a nested folder within the root folder
    const createNestedFolderResponse = await fetch(`${URL}${API_PATH}/folders?token=${TOKEN}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            name: "Invoices",
            isShared: false,
            parentFolderId: rootFolderId
        })
    });
    if (!createNestedFolderResponse.ok) {
        throw new Error(`Nested folder creation failed: ${createNestedFolderResponse.status} ${createNestedFolderResponse.statusText}`);
    }

    const nestedFolderData = await createNestedFolderResponse.json();
    const nestedFolderId = nestedFolderData.id;
    console.log(`Nested folder created with ID: ${nestedFolderId}`);

    // Step 3: Move an existing document into the nested folder
    const moveDocumentResponse = await fetch(`${URL}${API_PATH}/folders/move?token=${TOKEN}`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            docs: [
                { id: DOCUMENT_ID }
            ],
            folderId: nestedFolderId
        })
    });
    if (!moveDocumentResponse.ok) {
        throw new Error(`Document move failed: ${moveDocumentResponse.status} ${moveDocumentResponse.statusText}`);
    }

    const moveResult = await moveDocumentResponse.json();
    if (moveResult.errors === false) {
        console.log(`Successfully moved ${moveResult.count} document(s) to the nested folder`);
    } else {
        console.error('Some documents could not be moved:', moveResult.items);
    }

} catch (error) {
    console.error('Error in folder and document organization:', error.message);
}