5. Constructing Signing URLs

Constructing Signing URLs

Overview

This guide demonstrates how to construct direct signing URLs that allow you to seamlessly integrate Circularo's signing functionality into your applications. By using these URLs, you can redirect users directly to the signing interface without requiring them to navigate through email notifications.

Key benefits:

Create direct links to signing interfaces for both internal and external recipients
Integrate document signing directly into your application workflows
Improve user experience by eliminating the need to check email for signing links
Support embedded signing experiences within iframes or custom interfaces

Use Cases

E-commerce Checkout: Have customers sign terms and conditions or purchase agreements directly in the checkout flow
Customer Onboarding: Streamline new customer onboarding by embedding document signing in your registration process
Employee Portals: Allow employees to sign internal documents directly from your company portal
Service Applications: Enable clients to sign service agreements within your application workflow

Understanding the difference between recipient types is crucial for implementing the correct URL construction approach:

External recipient: A user without a Circularo account who will sign using a secure link
Internal recipient: A user with a Circularo account who will sign after authentication

Constructing URLs for External Recipients

External recipients need a secure method to access and sign documents. This approach requires implementing OTP (One-Time Password) verification to maintain security when bypassing the standard email notification flow.

Step 1: Request Signature with OTP Protection

First, share the document with the external recipient using OTP protection. This is crucial because you're bypassing the email notification, which normally serves as an initial authentication layer.

JSON

POST /share
{
  "id": "documentId",
  "type": "documentType",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "recipient@example.com",
      "phone": "+1234567890",  // For SMS OTP
      // OR
      "mail": "recipient@example.com"  // For Email OTP
    }
  ],
  "signatureFields": [
    {
      "user": ["recipient@example.com"],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [1],
      "position": {
        "percentX": 0.2,
        "percentY": 0.6,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      }
    }
  ]
}

The response will contain a shareId that you'll need for the next step:

JSON

{
  "shareId": "eNkm-YkBaRhWjrzWZ0-W",
  ...
}

OTP protection is mandatory when creating direct signing URLs for external recipients. Without it, the system will reject the URL generation request as it would create a security vulnerability.

Step 2: Obtain the Share Token

Next, validate the share to obtain a secure share token:

CODE

GET /share/{shareId}/validate

Example request:

CODE

GET /share/eNkm-YkBaRhWjrzWZ0-W/validate

The response will contain the shareToken needed to construct the signing URL:

JSON

{
  "shareToken": "91befa40e26bc81b828c2c6e8ced7f2555b0f1539a25a7ac888ccc75b3ec63ee",
  ...
}

If you didn't secure the document with OTP in Step 1, you'll receive a 400 error with the message: "Share needs to be secured by mail or phone OTP or oAuth."

Step 3: Construct the Signing URL

With the share token obtained, construct the signing URL using this format:

CODE

<frontendURL>/share?shareToken={shareToken}

Example:

CODE

https://sandbox.circularo.com/share?shareToken=91befa40e26bc81b828c2c6e8ced7f2555b0f1539a25a7ac888ccc75b3ec63ee

Step 4: User Experience Flow

When an external recipient accesses this URL:

They will be prompted to enter the OTP sent to their email or phone
After successful verification, they'll be taken directly to the signing interface
They can complete the signing process without needing a Circularo account
Once signed, they'll receive a confirmation and can download a copy of the signed document

For a seamless user experience, consider informing users that they'll receive an OTP and will need to enter it to access the document. This sets proper expectations and reduces confusion.

Constructing URLs for Internal Recipients

For internal recipients (users with Circularo accounts), the process is simpler as they already have authentication credentials.

Step 1: Request Signature

Share the document with the internal recipient:

JSON

POST /share
{
  "id": "documentId",
  "type": "documentType",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "internal.user@example.com"
    }
  ],
  "signatureFields": [
    {
      "user": ["internal.user@example.com"],
      "timestamp": false,
      "required": true,
      "type": "signature",
      "pages": [1],
      "position": {
        "percentX": 0.2,
        "percentY": 0.6,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      }
    }
  ]
}

Step 2: Construct the Signing URL

For internal recipients, construct the URL using this format:

CODE

<frontendURL>/#!/sign?documentId={documentId}&documentType={documentType}

Parameters:

documentId: The ID of the document to be signed (same as in Step 1)
documentType: The metadata definition of the document (same as in Step 1)

Example:

CODE

https://sandbox.circularo.com/#!/sign?documentId=e2461c31-9d65-472d-8d85-90bcefbac3f7&documentType=d_default

Step 3: User Experience Flow

When an internal recipient accesses this URL:

If not already logged in, they'll be prompted to sign in to their Circularo account
After authentication, they'll be taken directly to the signing interface
They can complete the signing process using their stored signature or creating a new one
Once signed, the document will be updated in their Circularo account

Advanced Implementation Considerations

Error Handling

Implement proper error handling for scenarios such as:

Expired or invalid share tokens
Documents that have already been signed
Authentication failures
Network connectivity issues

Testing Considerations

Before deploying to production:

Test the complete flow in your sandbox environment
Verify the user experience on different devices and browsers
Ensure OTP delivery and verification works correctly
Test with both internal and external recipients

Best Practices

Security First: Always use OTP protection for external recipients to maintain document security
Clear Instructions: Provide clear guidance to users about what to expect in the signing process
Responsive Design: Ensure your application handles the redirect and return flow smoothly on all devices
Fallback Options: Implement fallback mechanisms in case direct signing fails

Conclusion

Direct signing URLs provide a powerful way to integrate Circularo's document signing capabilities into your application workflows. By following the approaches outlined in this guide, you can create seamless signing experiences for both internal and external recipients while maintaining appropriate security measures.

For more advanced integration scenarios or custom requirements, consult the Circularo API documentation