1. Basic Document Creation

Basic Document Creation

This scenario demonstrates how to create a new document in Circularo with the minimum required data. Creating documents is a fundamental operation in the Circularo platform and serves as the starting point for document management workflows.

Key features:

Simple document creation with minimal required fields
Upload and use external PDF files as document content
Foundation for more complex document operations

Prerequisites

Before creating a document, you need:

A valid authentication token (see the "Authentication & Security" section for details)
Knowledge of available metadata definitions in your system
Knowledge of available workflow definitions in your system
A PDF file to upload as the document content

Metadata definitions and workflow definitions are configured in your Circularo instance. See the following scenarios to learn how to fetch them.

Step 1 - Upload a PDF file

Before creating a document, you need to upload the PDF file that will serve as the document content. This step uploads and stores a PDF file in the Circularo system.

The file is uploaded as a multipart/form-data request
The response includes the file ID that will be used in the document creation step
The response also includes storage quota information to help manage available space

The file upload is a separate step from document creation.

Endpoint

CODE

POST /files/saveFile

Request

JSON

POST /files/saveFile?token=kHnCWTmse9mTHMHYSzWioGMfzccjRs7hqyfge1ETU43ARl2rKZA9MhmeuN74eYVx

Content-Type: multipart/form-data

{
  "file": "blob",
  "fileName": "My PDF file"
}

Response

JSON

{
  "file": {
    "id": "TxcahFkrSAaigy6SFP2PaSvuzX2wFK0Aedvwqo7lgJp812d8i3G568BrAZux5yv2",
    "documentname": "My PDF file",
    "mimetype": "application/pdf",
    "size": 125840,
    ...
  },
  "storage": {
    "used": 2458732,
    "limit": 10737418240,
    ...
  },
  ...
}

The response contains the following important properties:

fileId - Located at file.id in the response.
- Example value: TxcahFkrSAaigy6SFP2PaSvuzX2wFK0Aedvwqo7lgJp812d8i3G568BrAZux5yv2

The PDF file has been successfully uploaded and stored in the system. The response includes the file ID that will be used in the next step to create a document based on this file.

The file.id is the unique identifier for the uploaded file (also referred as "file hash")
This ID will be used in the document creation step to reference this file
The storage information shows your current usage and available quota

Store the file ID for use in the next step. This ID is required to create a document based on this file.

Step 2 - Create a new document from PDF file

This endpoint creates a new document in the Circularo system using the previously uploaded PDF file.

The documentType parameter specifies which metadata definition to use
The workflow parameter defines the workflow that will be applied to the document
The definitionType parameter is set to "ext" to indicate an external file-based document
The pdfFile.content parameter references the file ID from the previous step
The documentTitle field sets the display name of the document

You must have the appropriate permissions to create documents with the specified metadata definition and workflow.

Endpoint

CODE

POST /documents

Request

JSON

POST /documents?token=kHnCWTmse9mTHMHYSzWioGMfzccjRs7hqyfge1ETU43ARl2rKZA9MhmeuN74eYVx

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "Sample Document",
    "pdfFile": {
      "content": "TxcahFkrSAaigy6SFP2PaSvuzX2wFK0Aedvwqo7lgJp812d8i3G568BrAZux5yv2"
    }
  },
  "definitionType": "ext",
  "workflow": "wf_archive"
}

Response

JSON

{
  "results": [
    {
      "documentId": "4f720144-5ad6-459d-a236-f947e7388dfa",
      "documentTitle": "Sample Document",
      "documentType": "d_default",
      "workflow": {
        "workflowType": "wf_archive",
        ...
      },
      ...
    }
  ],
  ...
}

The response contains the following important properties:

documentId - Located at results[0].documentId in the response.
- The unique identifier for the newly created document. Use this ID for all subsequent operations on this document.
- Example value: 4f720144-5ad6-459d-a236-f947e7388dfa

The document has been successfully created and is now available in the system.

The response includes the document ID which can be used for subsequent operations
The document is created with the specified metadata definition and workflow
The document content is based on the uploaded PDF file

Store the document ID for future operations such as updating, signing, or downloading the document.

Document Creation Summary

You have successfully created a document in the Circularo system using an external PDF file.

Key Concepts

Metadata Definitions: Templates that define the structure and fields of a document
Workflow Definitions: Processes that define the lifecycle and states of a document
External Documents: Documents created from uploaded files (PDF, Word, etc.)
Document ID: A unique identifier used to reference the document in all subsequent operations

Next Steps

With your document created, you can now:

Add attachments to the document
Sign or seal the document
Share the document with other users
Move the document through its workflow states

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 creation from PDF file
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key

try {
    // Step 1: Upload the PDF file
    const formData = new FormData();
    formData.append('fileName', 'My PDF file');
    formData.append('file', fs.createReadStream(pdfFilePath));  // This example uses Node.js 'fs' module to read the file

    const uploadResponse = await fetch(`${URL}${API_PATH}/files/saveFile?token=${TOKEN}`, {
        method: 'POST',
        body: formData
    });
    if (!uploadResponse.ok) {
        throw new Error(`File upload failed: ${uploadResponse.status} ${uploadResponse.statusText}`);
    }

    const uploadData = await uploadResponse.json();
    const fileId = uploadData.file.id;

    // Step 2: Create a document using the uploaded file
    const createResponse = await fetch(`${URL}${API_PATH}/documents?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            body: {
                documentType: "d_default",
                documentTitle: "Sample Document",
                pdfFile: {
                    content: fileId
                }
            },
            definitionType: "ext",
            workflow: "wf_archive"
        })
    });
    if (!createResponse.ok) {
        throw new Error(`Document creation failed: ${createResponse.status} ${createResponse.statusText}`);
    }

    const createData = await createResponse.json();
    const documentId = createData.results[0].documentId;

    console.log(`Document created successfully with ID: ${documentId}`);
    return documentId;
} catch (error) {
    console.error('Error creating document:', error.message);
    throw error;
}

The metadata definition and workflow must exist in your Circularo instance. The example uses "d_default" and "wf_archive" which are common defaults, but your system may use different values.