Skip to main content
Skip table of contents

3. Multiple Recipient Sharing

Multiple Recipient Sharing

This scenario demonstrates how to share documents with multiple recipients simultaneously, using different sharing configurations. This advanced sharing capability allows for complex workflows involving both internal and external recipients with various security requirements.

Key features:

  • Share documents with multiple recipients in a single request

  • Configure sequential workflows where recipients must act in a specific order

  • Set up parallel workflows where recipients can act simultaneously

  • Create group signing scenarios where only a subset of recipients need to sign

  • Mix internal and external recipients with different protection mechanisms

Prerequisites

Before setting up multiple recipient sharing, 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 both internal recipients and external email addresses you want to share with

  • Understanding of sequential vs. parallel workflows and their implications

When configuring complex sharing workflows, carefully consider the order of recipients and the security requirements for each step in the process.

Step 1 - Sequential Sharing with Mixed Recipients

This endpoint demonstrates how to share a document with multiple recipients in a sequential workflow. In this scenario, recipients must act in a specific order - first the internal recipient, then the external one.

  • The document is shared with both internal and external recipients in a single request

  • The sequential parameter is set to true, ensuring recipients act in the specified order

  • The external recipient is protected with a password for added security

  • Each recipient has a specific order number that determines when they can act on the document

  • Signature fields are positioned differently for each recipient

Sequential workflows are ideal for approval processes where actions must occur in a specific order, such as when a manager must sign before a client.

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=1kkT2gLgONvOkYCWsYyeFhtppWjACI8LEVKZfucmx4QAtlhzeS7NCxMQQOecQjJo

Content-Type: application/json

{
  "id": "7f9b75fc-e21f-47b4-ad21-357eac81c4f0",
  "type": "d_default",
  "objectType": "document",
  "sequential": true,  //Set to true for sequential workflow
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com",
      "order": 1  //Order 1 means this recipient acts first
    },
    {
      "sharePurpose": "sign",
      "shareTo": "client@example.com",
      "order": 2,  //Order 2 means this recipient acts second
      "password": "SecurePassword123",  //Password protection for external recipient
      "message": "Please use the password I sent you separately to access this document."
    }
  ],
  "signatureFields": [
    {
      "user": [
        "derek.trotter@circularo.com"
      ],
      "order": 1,
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.2,
        "percentY": 0.3,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    },
    {
      "user": [
        "client@example.com"
      ],
      "order": 2,
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.6,
        "percentY": 0.3,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "T2wI30cP7gGYLWR46ODf",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "7f9b75fc-e21f-47b4-ad21-357eac81c4f0",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    "sequential": true,
    "order": 1,
    ...
  },
  {
    "shareId": "UTq6bSHDd9G1qu713jkS",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "7f9b75fc-e21f-47b4-ad21-357eac81c4f0",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "client@example.com"
    ],
    "sequential": true,
    "order": 2,
    "passwordRequired": true,
    ...
  }
]

The document has been successfully shared with both recipients in a sequential workflow. The internal recipient will be notified first and must sign before the external recipient receives their notification.

Step 2 - Parallel Sharing with Mixed Recipients

This endpoint demonstrates how to share a document with multiple recipients in a parallel workflow. In this scenario, all recipients can act simultaneously without waiting for each other.

  • The document is shared with both internal and external recipients in a single request

  • The sequential parameter is set to false (or omitted), allowing recipients to act in parallel

  • The external recipient is protected with SMS verification for added security

  • All recipients are notified at the same time and can sign independently

Parallel workflows are ideal when you need multiple signatures but the order doesn't matter, such as when multiple team members need to approve a document.

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=1kkT2gLgONvOkYCWsYyeFhtppWjACI8LEVKZfucmx4QAtlhzeS7NCxMQQOecQjJo

Content-Type: application/json

{
  "id": "a3e2aca7-fa6b-4b9e-ab69-9cd929334c2e",
  "type": "d_default",
  "objectType": "document",
  "sequential": false,  //Set to false for parallel workflow (this is the default)
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com"
    },
    {
      "sharePurpose": "sign",
      "shareTo": "billy.spring@circularo.com"
    },
    {
      "sharePurpose": "sign",
      "shareTo": "client@example.com",
      "phone": "+1234567890",  //SMS verification for external recipient
      "message": "Please have your phone ready to receive the verification code."
    }
  ],
  "signatureFields": [
    {
      "user": [
        "derek.trotter@circularo.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.2,
        "percentY": 0.3,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    },
    {
      "user": [
        "billy.spring@circularo.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.2,
        "percentY": 0.4,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    },
    {
      "user": [
        "client@example.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.6,
        "percentY": 0.3,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "qkQIjLnuTErZlK1j1jZf",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "a3e2aca7-fa6b-4b9e-ab69-9cd929334c2e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    "sequential": false,
    ...
  },
  {
    "shareId": "TrWmkV7pM6Gh5Wcn8txf",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "a3e2aca7-fa6b-4b9e-ab69-9cd929334c2e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "billy.spring@circularo.com"
    ],
    "sequential": false,
    ...
  },
  {
    "shareId": "9rsHrC1oCoxL3z7uP0mO",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "a3e2aca7-fa6b-4b9e-ab69-9cd929334c2e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "client@example.com"
    ],
    "sequential": false,
    "otpPhone": "*****90",
    ...
  }
]

The document has been successfully shared with all recipients in a parallel workflow. All recipients will be notified simultaneously and can sign the document in any order.

In parallel workflows, all recipients are notified at the same time and can act independently. The document is considered fully signed only when all required signatures have been collected.

Step 3 - Group Signing with Quorum and Sequential Steps

This endpoint demonstrates a complex sharing scenario that combines group signing with a quorum requirement, followed by a sequential step. In this scenario, only one of two internal recipients needs to sign (quorum of 1), and then an external recipient must sign afterward.

  • The document is shared with three recipients in a single request

  • The first group consists of two internal recipients with a quorum of 1 (only one needs to sign)

  • The second step is an external recipient who must sign after the internal group

  • The sequential parameter is set to true to enforce the order of signing

  • The external recipient is protected with a password for added security

Group signing with quorum is ideal when you need approval from a department or team, but don't need every member to sign. For example, when any one of several managers can approve a request.

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=1kkT2gLgONvOkYCWsYyeFhtppWjACI8LEVKZfucmx4QAtlhzeS7NCxMQQOecQjJo

Content-Type: application/json

{
  "id": "7ba1623f-3ae5-4c7c-b47a-651c05939a3e",
  "type": "d_default",
  "objectType": "document",
  "sequential": true,
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com",
      "order": 1,  //Both internal recipients have the same order number, forming a group
      "quorum": 1  //Quorum of 1 means only one person from this order group needs to sign
    },
    {
      "sharePurpose": "sign",
      "shareTo": "billy.spring@circularo.com",
      "order": 1,  //Both internal recipients have the same order number, forming a group
      "quorum": 1
    },
    {
      "sharePurpose": "sign",
      "shareTo": "partner@example.com",
      "order": 2,
      "password": "SecurePassword456",
      "message": "Please sign after the internal team has approved."
    }
  ],
  "signatureFields": [
    {
      "user": [  //Both internal recipients share the same signature field
        "derek.trotter@circularo.com",
        "billy.spring@circularo.com"
      ],
      "order": 1,
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.2,
        "percentY": 0.3,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    },
    {
      "user": [
        "partner@example.com"
      ],
      "order": 2,
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.6,
        "percentY": 0.3,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "MRBP8dW2SHOFC1ur4cCg",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "7ba1623f-3ae5-4c7c-b47a-651c05939a3e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    "sequential": true,
    "order": 1,
    "quorum": 1,
    ...
  },
  {
    "shareId": "5SIEQrJezLXwIgidmQwP",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "7ba1623f-3ae5-4c7c-b47a-651c05939a3e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "billy.spring@circularo.com"
    ],
    "sequential": true,
    "order": 1,
    "quorum": 1,
    ...
  },
  {
    "shareId": "oQBxR0L3OIIZ90rJcvq9",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "7ba1623f-3ae5-4c7c-b47a-651c05939a3e",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "partner@example.com"
    ],
    "sequential": true,
    "order": 2,
    "passwordRequired": true,
    ...
  }
]

The document has been successfully shared with a group signing configuration. The two internal recipients will be notified first, and once one of them signs, the external recipient will be notified.

Multiple Recipient Sharing Summary

You have successfully shared documents with multiple recipients using different configurations:

  • Sequential Sharing: Recipients act in a specific order, with each step dependent on the completion of the previous step

  • Parallel Sharing: All recipients can act simultaneously without waiting for each other

  • Group Signing with Quorum: Only a specified number of recipients from a group need to complete an action

Key Concepts

  • Sequential Workflow: A process where recipients must act in a specific order

  • Parallel Workflow: A process where all recipients can act simultaneously

  • Quorum: The minimum number of recipients required to complete an action in a group

  • Order: A number that determines when a recipient should act in a sequential workflow

  • Mixed Recipients: Combining both internal and external recipients in a single workflow

Next Steps

With your advanced sharing configurations set up, you can now:

  • Monitor the status of each recipient's actions

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

  • Create even more complex workflows combining different sharing purposes

  • Explore additional protection mechanisms for external recipients

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 
// Multiple recipient sharing with different configurations
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 {
    // Sequential sharing with mixed recipients (internal and external)
    const sequentialShareResponse = 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",
            sequential: true,
            data: [
                {
                    sharePurpose: "sign",
                    shareTo: "internal.user@example.com",
                    order: 1
                },
                {
                    sharePurpose: "sign",
                    shareTo: "external.client@example.com",
                    order: 2,
                    password: "SecurePassword123",
                    message: "Please sign after our internal review"
                }
            ],
            signatureFields: [
                {
                    user: ["internal.user@example.com"],
                    order: 1,
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.2,
                        percentY: 0.3,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                },
                {
                    user: ["external.client@example.com"],
                    order: 2,
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.6,
                        percentY: 0.3,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                }
            ]
        })
    });
    if (!sequentialShareResponse.ok) {
        throw new Error(`Sequential sharing failed: ${sequentialShareResponse.status} ${sequentialShareResponse.statusText}`);
    }

    const sequentialShareData = await sequentialShareResponse.json();
    console.log(`Document shared sequentially with internal user and external client`);

    // Parallel sharing with multiple recipients
    const parallelShareResponse = 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",
            sequential: false, // or omit this parameter as false is the default
            data: [
                {
                    sharePurpose: "sign",
                    shareTo: "team.member1@example.com"
                },
                {
                    sharePurpose: "sign",
                    shareTo: "team.member2@example.com"
                },
                {
                    sharePurpose: "sign",
                    shareTo: "external.partner@example.com",
                    phone: "+1234567890",
                    message: "Please sign the agreement"
                }
            ],
            signatureFields: [
                {
                    user: ["team.member1@example.com"],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.2,
                        percentY: 0.3,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                },
                {
                    user: ["team.member2@example.com"],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.2,
                        percentY: 0.4,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                },
                {
                    user: ["external.partner@example.com"],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.6,
                        percentY: 0.3,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                }
            ]
        })
    });
    if (!parallelShareResponse.ok) {
        throw new Error(`Parallel sharing failed: ${parallelShareResponse.status} ${parallelShareResponse.statusText}`);
    }

    const parallelShareData = await parallelShareResponse.json();
    console.log(`Document shared in parallel with multiple recipients`);

    // Group signing with quorum followed by sequential step
    const groupShareResponse = 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",
            sequential: true,
            data: [
                {
                    sharePurpose: "sign",
                    shareTo: "manager1@example.com",
                    order: 1,
                    quorum: 1
                },
                {
                    sharePurpose: "sign",
                    shareTo: "manager2@example.com",
                    order: 1,
                    quorum: 1
                },
                {
                    sharePurpose: "sign",
                    shareTo: "client@example.com",
                    order: 2,
                    password: "SecurePassword456",
                    message: "Please sign after management approval"
                }
            ],
            signatureFields: [
                {
                    user: ["manager1@example.com", "manager2@example.com"],
                    order: 1,
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.2,
                        percentY: 0.3,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                },
                {
                    user: ["client@example.com"],
                    order: 2,
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.6,
                        percentY: 0.3,
                        percentWidth: 0.2,
                        percentHeight: 0.05
                    }
                }
            ]
        })
    });
    if (!groupShareResponse.ok) {
        throw new Error(`Group sharing failed: ${groupShareResponse.status} ${groupShareResponse.statusText}`);
    }

    const groupShareData = await groupShareResponse.json();
    console.log(`Document shared with group signing configuration`);

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