3. Document Download

Document Download

This scenario demonstrates how to download a document from Circularo. It shows the process of retrieving a document's details and then downloading its content.

Key features:

Retrieve document details including file hash
Download document content using the file hash
Simple and straightforward process for accessing document files

Prerequisites

Before downloading a document, you need:

A valid authentication token (see the "Authentication & Security" section for details)
The document ID of the document you want to download

This scenario assumes you already know the document ID. For information on how to search for documents, see the document search scenarios.

Step 1 - Retrieve document details

Before downloading a document, you need to retrieve its details to get the file hash. This step fetches the document information using the document ID.

The document ID uniquely identifies the document in the system
The response includes metadata about the document and its content
The file hash is needed for the actual download in the next step

Endpoint

CODE

GET /documents/:documentId

Request

JSON

GET /documents/e7c03a0f-f64e-4d75-b118-a3a461b26242?token=jx27Q0otWzjRQYs4hPBBCCx6kbT1qPlGsN6bOykDTu6heaA0liMJHD5vumq8oSCM

Response

JSON

{
  "results": [
    {
      "documentId": "e7c03a0f-f64e-4d75-b118-a3a461b26242",
      "documentTitle": "My document",
      "documentType": "d_default",
      "_version": 2,
      "pdfFile": {
        "content": "azvuib8Mkn0hwkfvmyHRIqd6D2rNYaA9GxtEJjIuUIB1Yx5L2wKkYLl2x1WgivIM",
        ...
      },
      "workflow": {
        "workflowType": "wf_archive",
        ...
      },
      ...
    }
  ],
  ...
}

The response contains the following important properties:

fileHash - Located at results[0].pdfFile.content in the response.
- The unique file hash (ID) that identifies the document's content. This hash is used to download the document file.
- Example value: azvuib8Mkn0hwkfvmyHRIqd6D2rNYaA9GxtEJjIuUIB1Yx5L2wKkYLl2x1WgivIM

The response includes comprehensive information about the document, including its version, metadata, workflow state, and file details.

The pdfFile.content field contains the file hash needed for downloading the document
The response also includes document version information, which is important for operations that modify the document
Document metadata such as title, type, and creation date are included in the response

Store the file hash for use in the next step. This hash is required to download the document content.

Step 2 - Download document file

This endpoint downloads the document file using the file hash obtained in the previous step.

The file hash uniquely identifies the document's content in the storage system
The response is the actual document file (typically a PDF)
This endpoint can be used to download any file stored in the system, not just document main files

File hashes are permanent and unique for each file version. If a document is modified, its file hash will change, and you'll need to retrieve the new hash.

Endpoint

CODE

GET /files/loadFile/hash/:hash

Request

JSON

GET /files/loadFile/hash/azvuib8Mkn0hwkfvmyHRIqd6D2rNYaA9GxtEJjIuUIB1Yx5L2wKkYLl2x1WgivIM?token=jx27Q0otWzjRQYs4hPBBCCx6kbT1qPlGsN6bOykDTu6heaA0liMJHD5vumq8oSCM

The response is the binary content of the document file.

The file is typically returned as a PDF, but could be in other formats depending on the document type
The response includes appropriate Content-Type and Content-Disposition headers
You can save this content to a file or display it in a viewer

Document Download Summary

You have successfully downloaded a document from the Circularo system.

Key Concepts

Document ID: Uniquely identifies a document in the system
File Hash: Uniquely identifies a file's content in the storage system
Two-Step Process: First retrieve document details, then download the file

Next Steps

With the document downloaded, you can now:

Display the document in a viewer
Save the document to your local system
Process the document content for further operations

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 download 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 the document you want to download

try {
    // Step 1: Retrieve document details to get the file hash
    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 fileHash = documentData.results[0].pdfFile.content;
    const documentTitle = documentData.results[0].documentTitle;

    // Step 2: Download the document file using the file hash
    const fileResponse = await fetch(`${URL}${API_PATH}/files/loadFile/hash/${fileHash}?token=${TOKEN}`);
    if (!fileResponse.ok) {
        throw new Error(`File download failed: ${fileResponse.status} ${fileResponse.statusText}`);
    }

    // Get the file content as a blob
    const fileBlob = await fileResponse.blob();

    // Option 1: Save the file (browser environment)
    const downloadLink = document.createElement('a');
    downloadLink.href = URL.createObjectURL(fileBlob);
    downloadLink.download = `${documentTitle}.pdf`;
    downloadLink.click();

    // Option 2: Save the file (Node.js environment)
    // const fs = require('fs');
    // const buffer = await fileResponse.buffer();
    // fs.writeFileSync(`${documentTitle}.pdf`, buffer);

    console.log(`Document downloaded successfully: ${documentTitle}`);
} catch (error) {
    console.error('Error downloading document:', error.message);
}