Skip to main content
Skip table of contents

2. External Sharing with Protection

External Sharing with Protection

This scenario demonstrates how to share documents with external recipients (people without Circularo accounts) and how to apply different protection mechanisms to secure these shares. External sharing is essential when collaborating with clients, partners, or other stakeholders outside your organization.

Key features:

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

  • Apply different protection mechanisms

  • Configure signature fields for external signers

  • Track sharing status and history

Prerequisites

Before sharing a document with external recipients, you need:

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

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

  • Valid email addresses for external recipients

  • Understanding of the different protection mechanisms and their security implications

When sharing documents with external recipients, consider the appropriate level of protection based on the document's sensitivity. Unprotected shares are convenient but less secure than those with password or SMS verification.

Step 1 - Share Document for Signing with External Recipient (No Protection)

The simplest form of external sharing is sending a document for signature without additional protection. This approach prioritizes convenience but offers less security.

  • The recipient receives an email with a link to access the document

  • No additional verification is required to access the document

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

  • The signing action is tracked in the document history

Unprotected external shares are convenient but provide minimal security. Only use this method for non-sensitive documents or when you're confident in the security of the recipient's email.

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=bZzKOtVoD5peLSjZWus4euM34AaENAmaPKCGiiBK1vRq8b1TE9JsbZBTNKZHYP2b

Content-Type: application/json

{
  "id": "e7f1eca4-3034-45f4-8b32-262503adc29e",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "client@example.com"
    }
  ],
  "signatureFields": [
    {
      "user": [
        "client@example.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.5,
        "percentY": 0.1,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "QXWsdsmQkFkgjory2AhI",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "e7f1eca4-3034-45f4-8b32-262503adc29e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "client@example.com"
    ],
    "passwordRequired": false,
    ...
  }
]

The document has been successfully shared with the external recipient. They will receive an email notification with a link to access the document.

When sharing with external recipients without protection, the security of the document relies solely on the security of the recipient's email account.

Step 2 - Share Document for Signing with External Recipient (Password Protected)

For increased security, you can protect shared documents with a password. The recipient will need both access to their email and knowledge of the password to view and sign the document.

  • The recipient receives an email with a link to access the document

  • The recipient must enter the provided password to access the document

  • The password adds an additional layer of security beyond email access

  • The signing action is tracked in the document history

For password-protected shares, communicate the password to the recipient through a separate, secure channel (e.g., phone call, SMS) rather than including it in the same email as the document link.

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=bZzKOtVoD5peLSjZWus4euM34AaENAmaPKCGiiBK1vRq8b1TE9JsbZBTNKZHYP2b

Content-Type: application/json

{
  "id": "a725e8fa-274f-4f22-a1eb-85c34ff5b56a",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "partner@example.com",
      "password": "SecurePassword123",  //The password the recipient must enter to access the document
      "message": "Please use the password I sent you via text message to access this document."  //Private message to the recipient
    }
  ],
  "signatureFields": [
    {
      "user": [
        "partner@example.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.5,
        "percentY": 0.1,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "DKtmC3LKVtp34s8IZKHs",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "a725e8fa-274f-4f22-a1eb-85c34ff5b56a",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "partner@example.com"
    ],
    "passwordRequired": true,
    ...
  }
]

The document has been successfully shared with the external recipient with password protection. They will receive an email notification with a link to access the document, but will need to enter the password to view and sign it.

The password should be communicated to the recipient through a separate, secure channel for maximum security.

Step 3 - Share Document for Signing with External Recipient (SMS Verification)

The secure method for external sharing is using SMS verification. This requires the recipient to have access to both their email and their phone to receive a one-time verification code.

  • The recipient receives an email with a link to access the document

  • When accessing the document, a one-time verification code is sent to their phone

  • The recipient must enter this code to access the document

  • This two-factor approach provides a high level of security for external shares

  • The signing action is tracked in the document history

SMS verification is ideal for sensitive documents as it implements a form of two-factor authentication, requiring access to both the recipient's email and phone.

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=bZzKOtVoD5peLSjZWus4euM34AaENAmaPKCGiiBK1vRq8b1TE9JsbZBTNKZHYP2b

Content-Type: application/json

{
  "id": "86823f58-3449-4668-9be4-97f13846505b",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "vendor@example.com",
      "phone": "+1234567890",
      "message": "Please have your phone ready to receive the verification code."
    }
  ],
  "signatureFields": [
    {
      "user": [
        "vendor@example.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.5,
        "percentY": 0.1,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "uQFEPq0XZXF7gWNGzWM0",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "86823f58-3449-4668-9be4-97f13846505b",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "vendor@example.com"
    ],
    "passwordRequired": false,
    "otpPhone": "*****90",
    ...
  }
]

The document has been successfully shared with the external recipient with SMS verification. They will receive an email notification with a link to access the document, and a verification code will be sent to their phone when they attempt to access it.

SMS verification provides a high level of security for external shares as it implements a form of two-factor authentication.

External Sharing Summary

You have successfully shared documents with external recipients using different protection mechanisms:

  • No Protection: Simple sharing that prioritizes convenience but offers minimal security

  • Password Protection: Adds a security layer requiring knowledge of a password

  • SMS Verification: Provides the highest security with two-factor authentication

Circularo supports additional protection mechanisms not demonstrated in this scenario, including Email OTP, OAuth provider verification, UAE Pass, and more. Refer to the API specification for details on implementing these advanced protection methods.

Key Concepts

  • External Sharing: Sharing with recipients who don't have Circularo accounts

  • Protection Mechanisms: Methods to secure access to shared documents, including password, SMS OTP, Email OTP, OAuth providers, UAE Pass, and more

  • Security Considerations: Choosing the appropriate protection level based on document sensitivity

Next Steps

With your document shared externally, 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 combined internal/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 
// External sharing with different protection mechanisms
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 signing with external recipient (no protection)
    const unprotectedShareResponse = 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: "client@example.com"
                }
            ],
            signatureFields: [
                {
                    user: ["client@example.com"],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.5,
                        percentY: 0.1,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                }
            ]
        })
    });
    if (!unprotectedShareResponse.ok) {
        throw new Error(`Unprotected sharing failed: ${unprotectedShareResponse.status} ${unprotectedShareResponse.statusText}`);
    }

    const unprotectedShareData = await unprotectedShareResponse.json();
    console.log(`Document shared for signing with client@example.com (no protection)`);

    // Share document for signing with external recipient (password protected)
    const passwordShareResponse = 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: "partner@example.com",
                    password: "SecurePassword123",
                    message: "Please use the password I sent you via text message to access this document."
                }
            ],
            signatureFields: [
                {
                    user: ["partner@example.com"],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.5,
                        percentY: 0.1,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                }
            ]
        })
    });
    if (!passwordShareResponse.ok) {
        throw new Error(`Password-protected sharing failed: ${passwordShareResponse.status} ${passwordShareResponse.statusText}`);
    }

    const passwordShareData = await passwordShareResponse.json();
    console.log(`Document shared for signing with partner@example.com (password protected)`);

    // Share document for signing with external recipient (SMS verification)
    const smsShareResponse = 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: "vendor@example.com",
                    phone: "+1234567890",
                    message: "Please have your phone ready to receive the verification code."
                }
            ],
            signatureFields: [
                {
                    user: ["vendor@example.com"],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.5,
                        percentY: 0.1,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                }
            ]
        })
    });
    if (!smsShareResponse.ok) {
        throw new Error(`SMS-protected sharing failed: ${smsShareResponse.status} ${smsShareResponse.statusText}`);
    }

    const smsShareData = await smsShareResponse.json();
    console.log(`Document shared for signing with vendor@example.com (SMS verification)`);

    console.log("External 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