6. Document Deletion

Document Deletion

This scenario demonstrates how to delete documents from the Circularo system. Document deletion is an important part of document lifecycle management, allowing you to remove documents that are no longer needed.

Key features:

Delete documents individually or in bulk
Choose between soft delete (trash) and permanent deletion
Simple and straightforward process for document removal

Prerequisites

Before deleting a document, you need:

A valid authentication token (see the "Authentication & Security" section for details)
The document ID and version of the document (optional) you want to delete
Appropriate permissions to delete documents in your Circularo instance

Document deletion can be permanent if the hardDelete option is used. Make sure you have appropriate backups or that the document is truly no longer needed before proceeding with permanent deletion.

Step 1 - Delete a document

This endpoint allows you to delete a document from the Circularo system. By default, documents are moved to the trash (soft delete) and can be restored later. You can also choose to permanently delete documents if needed.

The documents array contains the document IDs and versions (optional) to delete
The hardDelete parameter determines whether the deletion is permanent or moves the document to trash

Document version is optional and prevents conflicts when multiple users are working with the same document. You can retrieve the current document version using the GET /documents/:documentId endpoint.

Endpoint

CODE

DELETE /documents

Request

JSON

DELETE /documents?token=L50jut7mAc09CQEd6QM9oI8NOtTjSttwggoIOkNTbK0TA8K2PGXqzQGFnZwV0MiI&hardDelete=false

Content-Type: application/json

{
  "documents": [
    {
      "id": "7a306bc1-41ad-4fcf-a397-fc824252e4cc",
      "version": 17
    }
  ]
}

Response

JSON

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

The document has been successfully moved to the trash (or permanently deleted if hardDelete was set to true).

When hardDelete: false (default), the document is moved to trash and can be restored later
When hardDelete: true, the document is permanently deleted and cannot be recovered
The response includes details about any documents that could not be deleted, if applicable

To delete multiple documents in a single request, add more document objects to the documents array.

Document Deletion Summary

You have successfully learned how to delete documents from the Circularo system.

Key Concepts

Soft Delete: By default, documents are moved to trash and can be restored later
Hard Delete: When hardDelete is set to true, documents are permanently deleted
Bulk Operations: Multiple documents can be deleted in a single request
Version Control: Document version is optional to prevent conflicts

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

// Document deletion 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";

try {
    // First, get the current document version if you don't have it
    const documentResponse = await fetch(`${URL}${API_PATH}/documents/${DOCUMENT_ID}?token=${TOKEN}`);
    if (!documentResponse.ok) {
        throw new Error(`Failed to retrieve document: ${documentResponse.status} ${documentResponse.statusText}`);
    }

    const documentData = await documentResponse.json();
    if (!documentData.results || documentData.results.length === 0) {
        throw new Error('Document not found or no access');
    }

    const currentVersion = documentData.results[0]._version;

    // Delete the document (soft delete by default)
    const deleteResponse = await fetch(`${URL}${API_PATH}/documents?token=${TOKEN}`, {
        method: 'DELETE',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            documents: [{
                id: DOCUMENT_ID,
                version: currentVersion
            }]
        })
    });
    if (!deleteResponse.ok) {
        throw new Error(`Document deletion failed: ${deleteResponse.status} ${deleteResponse.statusText}`);
    }

    const deleteResult = await deleteResponse.json();
    if (!deleteResult.errors) {
        console.log('Document successfully moved to trash');
    } else {
        console.error('Some documents could not be deleted');
    }

} catch (error) {
    console.error('Error deleting document:', error.message);
}