Breadcrumbs

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:

GET /share/{shareId}/validate

Example request:

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:

<frontendURL>/share?shareToken={shareToken}

Example:

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:

<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:

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