Breadcrumbs

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

POST /share

Request

JSON
POST /share?token=sJjHHV2DOjfVuKefLrFOwCTEwbFFfytsBSioN2J4tnmSSLRKTVtgBk7RwgKcuI3K

Content-Type: application/json

{
  "id": "fcb6aa22-e35b-4bc2-8e10-38c076fa283b",
  "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": "4xK5SuwteEvo7nhNbkcl",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "fcb6aa22-e35b-4bc2-8e10-38c076fa283b",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  },
  {
    "shareId": "TH8PMKF3uikK5BpZ8XLz",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "fcb6aa22-e35b-4bc2-8e10-38c076fa283b",
    "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: 4xK5SuwteEvo7nhNbkcl

  • shareId2 - Located at [1].shareId in the response.

    • The unique identifier for the second share (to the second internal recipient).

    • Example value: TH8PMKF3uikK5BpZ8XLz

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

PUT /share/disable

Request

JSON
PUT /share/disable?token=sJjHHV2DOjfVuKefLrFOwCTEwbFFfytsBSioN2J4tnmSSLRKTVtgBk7RwgKcuI3K

Content-Type: application/json

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

Response

JSON
[
  {
    "id": "4xK5SuwteEvo7nhNbkcl",
    "error": false
  },
  {
    "id": "TH8PMKF3uikK5BpZ8XLz",
    "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);
}