4. Sign and Share in One Step

Sign and Share in One Step

This scenario demonstrates how to sign a document and share it for signature with another user in a single API call. This efficient workflow combines two common operations - applying your own signature and requesting signatures from others.

Key features:

Apply your own signature to a document
Simultaneously request signatures from other users
Position signatures precisely on the document
Streamline multi-party signing workflows

Prerequisites

Before using this combined sign and share workflow, you need:

A valid authentication token (see the "Authentication & Security" section for details)
A document to sign and share (see the "Document Management" section for details)
A signature image
Knowledge of the recipients you want to request signatures from

This approach is ideal for contracts and agreements that require multiple signatures, allowing you to apply your signature and request others' signatures in a single operation.

Step 1 - Sign Document and Request Signature

This endpoint demonstrates how to sign a document yourself and simultaneously request a signature from another user. This combined operation streamlines the signing workflow by reducing the number of API calls needed.

Your signature is applied to the document immediately
A signature request is sent to the specified recipient
Both signatures are positioned precisely on the document
The document's status is updated to reflect that it has been partially signed
The recipient is notified of the signature request

The `signatures` array contains your own signature that will be applied immediately, while the `signatureFields` array defines where the recipient's signature should be placed.

Endpoint

CODE

POST /share

Request

JSON

POST /share?token=pE5MBYwxNSOE9QMe5VSwqpi5RPE0EheaWDkw3V1wUwJMeZXVipJdirASFq5AV3Kz

Content-Type: application/json

{
  "id": "242f56d8-e6da-403a-b8c0-8da9326a81db",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",  //Recipient who will be requested to sign
      "shareTo": "derek.trotter@circularo.com"
    }
  ],
  "signatureFields": [  //Defines where the recipient's signature should be placed
    {
      "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
      }
    }
  ],
  "signatures": [  //Your own signature to be applied immediately
    {
      "type": "signature",
      "blob": "hhGguLPb9ywlSVjMBuKJgLg1qvnTejhzxiAAcl9KfoodTfhFjhQQGQWsBVTEVQko",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.5,
        "percentY": 0.3,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      }
    }
  ]
}

Response

JSON

[
  {
    "shareId": "IYbPlpDPva6qCh9kitNP",
    "isActive": true,
    "isPermanentViewToken": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "242f56d8-e6da-403a-b8c0-8da9326a81db",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    ...
  }
]

The document has been successfully signed by you and shared with the recipient for their signature. The recipient will receive a notification about the signature request.

Your signature has been applied to the document at the specified position
The document's status has been updated to reflect that it has been partially signed
A signature request has been sent to the recipient
The recipient can access the document through their Circularo dashboard or via the link in the notification

Step 2 - Check Document Share Status (Optional)

This endpoint demonstrates how to check the status of a document share. This is useful for monitoring the progress of signature requests and determining whether recipients have completed their actions.

Retrieves the current status of the document share
Shows whether the share is in progress, completed, cancelled, rejected, or expired
Helps track the workflow progress of shared documents
Allows you to take appropriate actions based on the share status

Endpoint

CODE

GET /documents/242f56d8-e6da-403a-b8c0-8da9326a81db

Request

JSON

GET /documents/242f56d8-e6da-403a-b8c0-8da9326a81db?token=pE5MBYwxNSOE9QMe5VSwqpi5RPE0EheaWDkw3V1wUwJMeZXVipJdirASFq5AV3Kz

Response

JSON

{
  "results": [
    {
      "documentId": "242f56d8-e6da-403a-b8c0-8da9326a81db",
      "documentType": "d_default",
      "isSigned": true,
      "workflow": {
        "shareStateName": "inprogress",
        ...
      },
      ...
    }
  ]
}

The response contains the following important properties:

shareStateName - Located at results[0].workflow.shareStateName in the response.
- The current status of the document share.
- Example value: inprogress

The document details have been successfully retrieved, including the share status.

inprogress: The share is active and waiting for recipient action
completed: All required signatures or approvals have been collected
cancelled: The share was cancelled by the document owner
rejected: The recipient rejected the signature or approval request
expired: The share has expired without being completed

Use this status information to determine when to send reminders, when to consider a workflow complete, or when to initiate alternative processes if a share was rejected or expired.

Sign and Share Summary

You have successfully signed a document and requested a signature from another user in a single operation. This combined workflow streamlines the signing process by reducing the number of API calls needed.

Key Concepts

Combined Workflow: Applying your signature and requesting others' signatures in a single API call
Signature Positioning: Precisely placing signatures at specific locations on the document
Signature Fields: Defining where recipients' signatures should be placed
Signature Application: Applying your own signature immediately while requesting others'
Share Status Monitoring: Checking the progress and state of signature requests

Next Steps

With your document signed and shared, you can now:

Monitor the status of the signature request (inprogress, completed, cancelled, rejected, or expired)
Send reminders to the recipient if they haven't signed yet
Download the fully signed document once all signatures are collected
Explore more complex signing workflows with multiple recipients and sequential signing

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

// Sign document and request signature in one step
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 sign and share
const DOCUMENT_TYPE = "d_default"; // Type of the document
const SIGNATURE_IMAGE_ID = "YOUR_SIGNATURE_IMAGE_ID"; // ID of your signature image
const RECIPIENT_EMAIL = "recipient@example.com"; // Email of the person who should sign

try {
    // Sign document and request signature in one step
    const signAndShareResponse = 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
                }
            ],
            // Define where the recipient's signature should be placed
            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
                    }
                }
            ],
            // Your own signature to be applied immediately
            signatures: [
                {
                    type: "signature",
                    blob: SIGNATURE_IMAGE_ID,
                    pages: [1],
                    position: {
                        percentX: 0.5,
                        percentY: 0.3,
                        percentWidth: 0.4,
                        percentHeight: 0.1
                    }
                }
            ]
        })
    });
    if (!signAndShareResponse.ok) {
        throw new Error(`Sign and share failed: ${signAndShareResponse.status} ${signAndShareResponse.statusText}`);
    }

    const signAndShareData = await signAndShareResponse.json();
    console.log(`Document signed and shared for signature with ${RECIPIENT_EMAIL}`);
    console.log(`Share ID: ${signAndShareData[0].shareId}`);

    // Check document status and share state (Optional)
    const documentStatusResponse = await fetch(`${URL}${API_PATH}/documents/${DOCUMENT_ID}?token=${TOKEN}`);
    if (!documentStatusResponse.ok) {
        throw new Error(`Failed to get document status: ${documentStatusResponse.status} ${documentStatusResponse.statusText}`);
    }

    // Check the share status
    const documentData = await documentStatusResponse.json();
    const shareStatus = documentData.results[0].workflow.shareStateName;
    console.log(`Share status: ${shareStatus}`);

    // Take action based on share status
    switch(shareStatus) {
        case "inprogress":
            console.log("The share is active and waiting for recipient action");
            break;
        case "completed":
            console.log("All required signatures have been collected");
            break;
        case "cancelled":
            console.log("The share was cancelled by the document owner");
            break;
        case "rejected":
            console.log("The recipient rejected the signature request");
            break;
        case "expired":
            console.log("The share has expired without being completed");
            break;
        default:
            console.log(`Unknown share status: ${shareStatus}`);
    }

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