5. Cancelling Shares

Cancelling Shares

This scenario demonstrates how to cancel active shares in the Circularo system. Cancelling shares is an important operation that allows you to revoke access to documents that have been shared incorrectly, need revision, or are no longer relevant.

Key features:

Cancel active shares to immediately revoke recipient access
Provide an optional message explaining why the share was cancelled
Cancel an entire sharing process with a single API call
Track cancellation in the document history

Prerequisites

Before cancelling shares, you need:

A valid authentication token (see the "Authentication & Security" section for details)
An active share ID from a previously shared document
Appropriate permissions (only the document owner or the original sharer can cancel shares)

Step 1 - Share Document with Multiple Internal Recipients

Before we can demonstrate cancelling shares, we need to create some active shares. This endpoint shares a document with two internal recipients for signing.

The document is shared with two internal recipients in a single request
Both recipients can sign the document in parallel
Each recipient has their own signature field positioned on the document
The sharing process creates multiple share records that will all be cancelled together when any one is cancelled

Endpoint

CODE

POST /share

Request

JSON

POST /share?token=SiawLBTaQwmX4M1pQZRhOgLpJYGs0dVeKwjtknJa0bFSLfXFCEL8qyP93einfk5Y

Content-Type: application/json

{
  "id": "ad97f704-f35f-430b-91fc-84f7669e099d",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com"
    },
    {
      "sharePurpose": "sign",
      "shareTo": "billy.spring@circularo.com"
    }
  ],
  "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.6,
        "percentY": 0.3,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      }
    }
  ]
}

Response

JSON

[
  {
    "shareId": "iCwNQkEzg3AsQbXPSltw",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "ad97f704-f35f-430b-91fc-84f7669e099d",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  },
  {
    "shareId": "4LvhgN8i4QxydRWhKqf3",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "ad97f704-f35f-430b-91fc-84f7669e099d",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "billy.spring@circularo.com"
    ],
    ...
  }
]

The response contains the following important properties:

shareId1 - Located at [0].shareId in the response.
- The unique identifier for the first share (to the first internal recipient).
- Example value: iCwNQkEzg3AsQbXPSltw
shareId2 - Located at [1].shareId in the response.
- The unique identifier for the second share (to the second internal recipient).
- Example value: 4LvhgN8i4QxydRWhKqf3

The document has been successfully shared with both internal recipients. Each recipient will receive a notification about the signature request.

The response includes share IDs for each recipient. These IDs will be used in the next step to cancel the shares.

Step 2 - Cancel Active Shares

This endpoint demonstrates how to cancel active shares. When you cancel a share, the recipient immediately loses access to the document, and the share is marked as cancelled in the system.

You can cancel one or more shares in a single request
When cancelling any share in a sharing process, the entire process is cancelled
The cancellation is tracked in the document history

In this example, we're only specifying one of the two share IDs. However, both shares will be cancelled because they belong to the same sharing process.

Endpoint

CODE

PUT /share/disable

Request

JSON

PUT /share/disable?token=SiawLBTaQwmX4M1pQZRhOgLpJYGs0dVeKwjtknJa0bFSLfXFCEL8qyP93einfk5Y

Content-Type: application/json

{
  "shareIds": [  //Array of share IDs to cancel (only one is needed to cancel the entire process)
    "iCwNQkEzg3AsQbXPSltw"
  ]
}

Response

JSON

[
  {
    "id": "iCwNQkEzg3AsQbXPSltw",
    "error": false
  },
  {
    "id": "4LvhgN8i4QxydRWhKqf3",
    "error": false
  }
]

The shares have been successfully cancelled. All recipients will immediately lose access to the document.

When you cancel any share in a sharing process, all related shares are automatically cancelled as well. This ensures that the entire sharing workflow is properly terminated.

Cancelling Shares Summary

You have successfully cancelled active shares in the Circularo system. This operation is important for managing document access and maintaining security.

Key Concepts

Share Cancellation: Immediately revokes recipient access to shared documents
Process-Wide Cancellation: Cancelling any share in a process cancels all related shares
Share ID: Unique identifier used to target specific shares for cancellation

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

// Cancel active shares
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key
const SHARE_ID = "SHARE_ID_TO_CANCEL"; // ID of the share to cancel

try {
    // Cancel the share
    const cancelShareResponse = await fetch(`${URL}${API_PATH}/share/disable?token=${TOKEN}`, {
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            shareIds: [SHARE_ID]
        })
    });
    if (!cancelShareResponse.ok) {
        throw new Error(`Share cancellation failed: ${cancelShareResponse.status} ${cancelShareResponse.statusText}`);
    }

    const cancelShareData = await cancelShareResponse.json();

    // Check if cancellation was successful
    if (cancelShareData.length > 0 && !cancelShareData[0].error) {
        console.log(`Share ${SHARE_ID} successfully cancelled`);
        console.log(`All related shares in the same process have also been cancelled`);
    } else {
        console.log(`Error cancelling share: ${JSON.stringify(cancelShareData)}`);
    }

} catch (error) {
    console.error('Error cancelling share:', error.message);
}