Skip to main content
Skip table of contents

1. Internal Sharing

Internal Sharing

This scenario demonstrates how to share documents with other users within your Circularo organization. Internal sharing is a fundamental operation that allows for collaboration between team members with different levels of access and permissions.

Key features:

  • Share documents with internal recipients (registered in your Circularo organization)

  • Configure different sharing purposes (view, edit, sign, approve, ...)

  • Control access rights for shared documents

  • Track sharing status and history

Prerequisites

Before sharing a document, you need:

  • A valid authentication token (see the "Authentication & Security" section for details)

  • A document to share (see the "Document Management" section for details)

  • Knowledge of the internal recipients you want to share with

  • Understanding of the different sharing purposes and their implications

Step 1 - Share Document for Viewing

The most basic form of sharing is granting view access to another user. This allows the recipient to view the document without the ability to modify it.

  • The recipient can view the document content and metadata

  • The recipient cannot modify the document

  • The sharing status is tracked in the document history

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=SWAX9xUMXARKZd6EgVaTpKylXUoM08G0LhhAUpOqZwt0i2Jj0F4HGRjBnWruwLL2

Content-Type: application/json

{
  "id": "12d60c26-5bd0-44c6-bd93-45a9baab7512",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "view",
      "shareTo": "derek.trotter@circularo.com"
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "Yjee6jxaZf6ebG7Ux91M",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "view",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "12d60c26-5bd0-44c6-bd93-45a9baab7512",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  }
]

The document has been successfully shared for viewing. The recipient can access the document through their Circularo dashboard.

When sharing for viewing, the recipient can only view the document and cannot make any changes to it.

Step 2 - Share Document for Editing

Sharing a document for editing grants the recipient permission to make changes to the document. This is useful when you need collaborative input or modifications from team members.

  • The recipient can view and modify the document content

  • The recipient can update document metadata

  • All changes are tracked in the document history

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=SWAX9xUMXARKZd6EgVaTpKylXUoM08G0LhhAUpOqZwt0i2Jj0F4HGRjBnWruwLL2

Content-Type: application/json

{
  "id": "a89094e8-27ee-4db0-98e8-e3ebd1b2698e",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "edit",
      "shareTo": "derek.trotter@circularo.com"
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "CghfcPG4FZv6GxfoSQeq",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "edit",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "a89094e8-27ee-4db0-98e8-e3ebd1b2698e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  }
]

The document has been successfully shared for editing. The recipient can access the document through their Circularo dashboard.

When sharing for editing, the recipient can make changes to the document content and metadata.

Step 3 - Share Document for Approval/Acceptance/Review

Sharing a document for approval (or accept/review) requests the recipient to review and formally approve the document. This is commonly used in review workflows.

  • The recipient can view the document and provide approval

  • The approval is tracked in the document history

  • The document's status is updated once approved

Approval (also accept/review) sharing is ideal for review processes where a formal sign-off is needed but a full signature is not required.

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=SWAX9xUMXARKZd6EgVaTpKylXUoM08G0LhhAUpOqZwt0i2Jj0F4HGRjBnWruwLL2

Content-Type: application/json

{
  "id": "81a48ebb-d24d-452b-9e34-472e099fc3f8",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "approve",  //Also you can also use \"accept\" or \"review\"
      "shareTo": "derek.trotter@circularo.com"
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "jrVVSTOWY9eKqCr2lhko",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "approve",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "81a48ebb-d24d-452b-9e34-472e099fc3f8",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  }
]

The document has been successfully shared for approval. The recipient can access the document through their Circularo dashboard.

When sharing for approval, the recipient will be prompted to approve the document.

Step 4 - Share Document for Signing

Sharing a document for signing requests the recipient to electronically sign the document. This is essential for formal agreements.

  • The recipient can view the document and add their electronic signature

  • The signature is legally binding and compliant with electronic signature regulations (depending on signature type)

  • The signing action is tracked in the document history

  • The document's status is updated once signed

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=SWAX9xUMXARKZd6EgVaTpKylXUoM08G0LhhAUpOqZwt0i2Jj0F4HGRjBnWruwLL2

Content-Type: application/json

{
  "id": "452a2424-127e-4269-9e94-289fc01ec024",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com"
    }
  ],
  "signatureFields": [
    {
      "user": [  //User who has to fill the signature field
        "derek.trotter@circularo.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [  //Page on which the signature field will be located
        1
      ],
      "position": {  //Exact position of the signature on the page
        "percentX": 0.5,
        "percentY": 0.1,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "0fPr6bD5eVMLKmZTPEqI",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "452a2424-127e-4269-9e94-289fc01ec024",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  }
]

The document has been successfully shared for signing. The recipient can access the document through their Circularo dashboard.

When sharing for signing, the recipient will be prompted to add their electronic signature to the document.

Sometimes you need to create a permanent link to a document that can be shared with anyone, without requiring authentication. This is useful for public documents or when you need to embed document links in emails.

  • The link provides view-only access to the document

  • The link remains valid indefinitely (unlike regular shares that can expire)

  • Anyone with the link can view the document without authentication

  • Ideal for public documents or embedding in emails

Since permanent links provide access without authentication, use them only for documents that don't contain sensitive information.

Endpoint

CODE 
POST /share/permanent

Request

JSON 
POST /share/permanent?token=SWAX9xUMXARKZd6EgVaTpKylXUoM08G0LhhAUpOqZwt0i2Jj0F4HGRjBnWruwLL2

Content-Type: application/json

{
  "id": "c47c3bd8-d485-400d-ab8c-b83b26942579",
  "type": "d_default",
  "objectType": "document"
}

Response

JSON 
{
  "shareToken": "gIjmZpdCc5lcUeZaQRkAYF5mFvj59GThe7snBWBe6JalAZHztne0j2xI1MLsUPrE"
}

The response contains the following important properties:

  • shareToken - Located at shareToken in the response.

    • The permanent share token that can be used to create a link to the document.

    • Example value: gIjmZpdCc5lcUeZaQRkAYF5mFvj59GThe7snBWBe6JalAZHztne0j2xI1MLsUPrE

A permanent view token has been successfully created for the document. This token can be used to create a link that provides view-only access to the document without requiring authentication.

  • The token can be used to create a link in the format: {CircularoFeUrl}/share?shareToken={shareToken}

  • The link remains valid indefinitely and can be shared with anyone

  • The link provides view-only access to the document

Internal Sharing Summary

You have successfully shared documents with internal recipient for different purposes:

  • View: Basic access to view the document without modification rights

  • Edit: Permission to view and modify the document

  • Approve/Accept/Review: Request for formal approval/acceptance/review of the document

  • Sign: Request for electronic signature on the document

  • Permanent View Link: Create a permanent link that provides view-only access without authentication

Key Concepts

  • Sharing Purpose: Defines what actions the recipient can perform on the document

  • Internal Sharing: Sharing with users registered in your Circularo organization

  • Share ID: A unique identifier for each sharing action

Next Steps

With your document shared, you can now:

  • Monitor the status of shared documents

  • Send reminders to recipients who haven't acted on shared documents

  • Revoke sharing access if needed

  • Explore advanced sharing options like sequential workflows and external sharing

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 sharing with internal recipients
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 to share
const DOCUMENT_TYPE = "d_default"; // Type of the document

try {
    // Share document for viewing with user1
    const viewShareResponse = await fetch(`${URL}${API_PATH}/share?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            id: DOCUMENT_ID,
            type: DOCUMENT_TYPE,
            objectType: "document",
            data: [
                {
                    sharePurpose: "view",
                    shareTo: "user1@example.com"
                }
            ]
        })
    });
    if (!viewShareResponse.ok) {
        throw new Error(`View sharing failed: ${viewShareResponse.status} ${viewShareResponse.statusText}`);
    }

    const viewShareData = await viewShareResponse.json();
    console.log(`Document shared for viewing with user1@example.com`);

    // Share document for editing with user2
    const editShareResponse = await fetch(`${URL}${API_PATH}/share?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            id: DOCUMENT_ID,
            type: DOCUMENT_TYPE,
            objectType: "document",
            data: [
                {
                    sharePurpose: "edit",
                    shareTo: "user2@example.com"
                }
            ]
        })
    });
    if (!editShareResponse.ok) {
        throw new Error(`Edit sharing failed: ${editShareResponse.status} ${editShareResponse.statusText}`);
    }

    const editShareData = await editShareResponse.json();
    console.log(`Document shared for editing with user2@example.com`);

    // Share document for approval with user3
    const approveShareResponse = await fetch(`${URL}${API_PATH}/share?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            id: DOCUMENT_ID,
            type: DOCUMENT_TYPE,
            objectType: "document",
            data: [
                {
                    sharePurpose: "approve",
                    shareTo: "user3@example.com"
                }
            ]
        })
    });
    if (!approveShareResponse.ok) {
        throw new Error(`Approve sharing failed: ${approveShareResponse.status} ${approveShareResponse.statusText}`);
    }

    const approveShareData = await approveShareResponse.json();
    console.log(`Document shared for approval with user3@example.com`);

    // Share document for signing with user4
    const signShareResponse = await fetch(`${URL}${API_PATH}/share?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            id: DOCUMENT_ID,
            type: DOCUMENT_TYPE,
            objectType: "document",
            data: [
                {
                    sharePurpose: "sign",
                    shareTo: "user4@example.com"
                }
            ],
            signatureFields: [
                {
                    user: ["user4@example.com"],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.5,
                        percentY: 0.1,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                }
            ]
        })
    });
    if (!signShareResponse.ok) {
        throw new Error(`Sign sharing failed: ${signShareResponse.status} ${signShareResponse.statusText}`);
    }

    const signShareData = await signShareResponse.json();
    console.log(`Document shared for signing with user4@example.com`);

    // Create a permanent view link for the document
    const permanentLinkResponse = await fetch(`${URL}${API_PATH}/share/permanent?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            id: DOCUMENT_ID,
            type: DOCUMENT_TYPE,
            objectType: "document"
        })
    });
    if (!permanentLinkResponse.ok) {
        throw new Error(`Creating permanent link failed: ${permanentLinkResponse.status} ${permanentLinkResponse.statusText}`);
    }

    const permanentLinkData = await permanentLinkResponse.json();
    const shareToken = permanentLinkData.shareToken;
    const permanentLink = `${URL}/share?shareToken=${shareToken}`;
    console.log(`Permanent view link created: ${permanentLink}`);

    console.log("Document sharing completed successfully");

} catch (error) {
    console.error('Error sharing document:', error.message);
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close