2. Sending Share Reminders

Sending Share Reminders

This scenario demonstrates how to configure automatic reminders and send manual reminders to recipients who have pending actions on shared documents. Reminders are an essential tool for improving document workflow completion rates and reducing the time needed to collect all required signatures or approvals.

Key features:

Configure automatic reminders during document sharing to send periodic notifications
Send manual reminders to recipients who haven't completed their required actions
Target all eligible recipients of a document or specific individuals
Improve document workflow completion rates

Prerequisites

Before working with reminders, you need:

A valid authentication token (see the "Authentication & Security" section for details)
A document that has been shared with one or more recipients
Knowledge of the document ID or specific share IDs
Appropriate permissions (only document owners or original sharers can send reminders)

Reminders can only be sent for shares that require action (sign, approve, review) and haven't been completed yet. The system also enforces a limit of one reminder per day for each share to prevent notification spam.

Step 1 - Share Document with Automatic Reminders

This endpoint demonstrates how to share a document with a recipient for signing while configuring automatic reminders. Automatic reminders are sent periodically without requiring additional API calls, ensuring recipients are prompted to complete their actions.

The document is shared with the recipient for signing
Automatic reminders are configured to periodically notify the recipient
A signature field is positioned on the document for the recipient
The recipient receives a notification about the signature request
The document enters a workflow state waiting for the recipient's signature

Automatic reminders are ideal for important documents where timely completion is critical, reducing the need for manual follow-up.

Endpoint

CODE

POST /share

Request

JSON

POST /share?token=hvlAT0OOhtxCBX45AW78Uxb1JYCyvEOn9em7O1FLfGgw6RkKyYF8EBSSTZ1TuqUV

Content-Type: application/json

{
  "id": "bd0d9ea4-5c87-4c32-a0a9-66d023f493d0",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com",
      "automaticReminder": {  //Configuration for automatic periodic reminders
        "start": "2025-10-17T13:00:00.000+02:00",  //Date when the first automatic reminder will be sent
        "intervalDays": 3  //Number of days between subsequent reminders
      }
    }
  ],
  "signatureFields": [
    {
      "user": [
        "derek.trotter@circularo.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.2,
        "percentY": 0.6,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      }
    }
  ]
}

Response

JSON

[
  {
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "bd0d9ea4-5c87-4c32-a0a9-66d023f493d0",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  }
]

The document has been successfully shared with the recipient for signing, and automatic reminders have been configured. The recipient will receive a notification about the signature request immediately, and then periodic reminders according to the specified schedule.

The first automatic reminder will be sent on the specified start date
Subsequent reminders will be sent every 3 days until the document is signed
Automatic reminders stop once the recipient completes their required action
No additional API calls are needed for these automatic reminders

In addition to automatic reminders, you can also send manual reminders using the endpoints below if you need to prompt recipients outside the automatic schedule.

Step 2 - Send Manual Reminder to All Document Recipients

This endpoint demonstrates how to send manual reminders to all eligible recipients of a document who have pending actions. This is useful when you want to follow up with everyone who hasn't completed their required actions yet, in addition to any automatic reminders that may be configured.

Sends manual reminders to all eligible recipients of the specified document
Only recipients with pending actions (sign, approve, review) will receive reminders
Recipients who have already completed their actions won't receive reminders
The system enforces a limit of one reminder per day for each share

Endpoint

CODE

POST /share/reminder

Request

JSON

POST /share/reminder?token=hvlAT0OOhtxCBX45AW78Uxb1JYCyvEOn9em7O1FLfGgw6RkKyYF8EBSSTZ1TuqUV

Content-Type: application/json

{
  "documentId": "bd0d9ea4-5c87-4c32-a0a9-66d023f493d0"  //ID of the document to send reminders for
}

Response

JSON

{
  "status": "SUCCESS"
}

Manual reminder notifications have been successfully sent to all eligible recipients of the document who have pending actions.

Only recipients with pending actions received reminders
Recipients who have already completed their actions didn't receive reminders
The system enforces a limit of one reminder per day for each share

Share Reminders Summary

You have successfully learned how to configure automatic reminders and send manual reminders to recipients who have pending actions on shared documents.

Key Concepts

Automatic Reminders: Configure periodic reminders during document sharing that are sent automatically
Manual Reminders: Send additional reminders on-demand when needed
Reminder Limits: The system enforces a limit of one reminder per day for each share
Eligibility: Only recipients with pending actions (sign, approve, review) can receive reminders

Next Steps

With reminders in place, you can now:

Monitor the status of shared documents
Send additional manual reminders if needed (respecting the daily limit)
Explore more 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

// Share reminders example
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 and send reminders for
const DOCUMENT_TYPE = "d_default"; // Type of the document
const RECIPIENT_EMAIL = "recipient@example.com"; // Email of the person who should sign

try {
    // Step 1: Share document with automatic reminders
    const shareResponse = 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: RECIPIENT_EMAIL,
                    // Configure automatic reminders
                    automaticReminder: {
                        // First reminder will be sent on this date
                        start: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days from now
                        // Subsequent reminders will be sent every 3 days
                        intervalDays: 3
                    }
                }
            ],
            signatureFields: [
                {
                    user: [RECIPIENT_EMAIL],
                    timestamp: false,
                    required: true,
                    type: "signature",
                    pages: [1],
                    position: {
                        percentX: 0.2,
                        percentY: 0.6,
                        percentWidth: 0.4,
                        percentHeight: 0.1
                    }
                }
            ]
        })
    });
    if (!shareResponse.ok) {
        throw new Error(`Share failed: ${shareResponse.status} ${shareResponse.statusText}`);
    }

    const shareData = await shareResponse.json();
    console.log(`Document shared with automatic reminders configured. Share ID: ${shareData[0].shareId}`);

    //Some time later

    // Step 2: Send a manual reminder to all recipients (if needed out of automatic reminders schedule)
    const documentReminderResponse = await fetch(`${URL}${API_PATH}/share/reminder?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            documentId: DOCUMENT_ID
        })
    });
    if (!documentReminderResponse.ok) {
        throw new Error(`Document reminder failed: ${documentReminderResponse.status} ${documentReminderResponse.statusText}`);
    }

    console.log(`Manual reminders sent to all eligible recipients of document ${DOCUMENT_ID}`);

} catch (error) {
    console.error('Error in reminder workflow:', error.message);
}