Construct signing URL

Introduction

The purpose of this guide is to show how to construct signing URL that your application will be redirecting to.

Usecase can be a web application for online orders that needs contract signed at the end of the order process. The user is directly redirected to the signing screen without the need to click the signing link in the email.

Our first example will be how to construct an URL like this = for external users.

Another usecase can be an application that redirects users to the sign screen in an iframe window. This will be covered in second example that is aimed at internal users.

External user = User without a Circularo account

Internal user = User with a Circularo account

1. Construct URL for external user

Step 1 - Request signature with OTP

The important thing to understand here is that by going with this option means that we are bypassing the email notification which an initial level of authentication (user needs to have access to his email to access the document sent to him). That means we need to replace this with another mean of authentication - OTP.

Read more about requesting signature - Request signature

Response

The response contains shareId required in next step:

JSON

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

Step 2 - Obtain share token

Endpoint

CODE

GET /share/{shareId}/validate

Request

CODE

GET /share/eNkm-YkBaRhWjrzWZ0-W/validate

Response

The response contains shareToken required in next step:

JSON

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

If you do not secure the document with OTP, you will receive following 400 error in this step:

CODE

Share needs to be secured by mail or phone OTP or oAuth.

Step 3 - Construct URL

Construct URL in following way:

CODE

<frontendURL>/share?shareToken={shareToken}

Example for our case

CODE

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

Once you redirect the external user to this link he will be prompted to insert OTP and after successful authentication will be able to sign.

2. Construct URL for internal user

Step 1 - Request signature

This is similar to the first scenario, the only difference is that you do not need to send OTP along with the signature request.

Save document ID since its required for the next step

Step 2 - Construct URL

Construct URL in following way:

CODE

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

documentId - saved from previous step
documentType - always d_default

Example

CODE

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

Notes:

internal user will be promted to sign in to his Circularo account
in case the user is already logged in to his account he will be redirected directly to signing screen