/auth

This resource and operations allow external platform to login, logout and verify the token validity.

Based on how authentication is done, parameters will vary. Refer to the API access and Authentication section above.

On a successful authentication, a token is returned in the X-Auth-Token response header. The token is a signed JWT token which, when decoded, contains various details about the logged-in user.

The token must be sent in every subsequent request, in the X-Auth-Token header or as a request parameter with name X-Auth-Token. Please refer to each operation details.

The token expires after 30 minutes of inactivity. The integrator must re-authentify if token has expired.

The token MUST be secured when stored locally.

The token contains some mutable fields. When at least one of these fields changes, a new token is returned in the X-Auth-Token response header. The new token MUST be used for subsequent requests, and the previous one destroyed.

post

User login using a username, a password and a tenant.

post

User logout

head

Method to verify if X-Auth-Token is still valid

/documents

This resource and operations allow external platform to upload document to be used in a given workflow.

Should be used to upload document in multi-part. If the platform supports base64 encoding, document should be uploaded using the resource /workflows.

Only PDF document can be uploaded. The file content must NOT be encoded in the request.

Document upload is required before the workflow initialization.

Document can be assigned to a single workflow. If it should be used in different workflows, it must be uploaded multiple times.

A signing project can consist of one or multiple documents. Each document must be uploaded separately as IDs are returned and must be referred in the /workflows operations.

Each document can have zero, one or multiple signers (to be defined using the /workflows resource). A signing project must have at least 1 signer defined in order to be launched.

Each document can be converted to the PDF/A standard if required at upload time.

When using this resource, the documentId property must be saved in the response and used in subsequent /workflows call.

post

Document upload

/workflows

This resource is the main one to be used to set the project various properties and retrieve information (documents, audit trail, URL, state). Here are few key concepts to understand first.


Signature Modes

Two modes are currently supported: remote signing or embedded signing. The mode is set using the workflow.actions[i].mode property.


Remote Signing

Remote Signing is the normal mode of signing where the signature process is triggered by an email sent to the signer. It is also used to fill Text Zone.

Following completion of the 2nd authentication method (sms,call,secret), the signer can complete its step and workflow will continue (either end or move to next signer).

To add a remote signer, the following parameters should be set:

  • workflow.actions[i].mode: must have value remote.


Embedded Signing

Embedded Signing allows integration of the signature process into an existing platform, either through an iframe or a redirect. In this mode, the external platform is responsible to authenticate the signer, as the email+link verification step is skipped.

Embedded Signing is not available on the main tenant. An organization must have its own tenant and configured accordingly to enable embedded signing.

An embedded signer cannot be defined in a parallel sequence. Secret amr cannot be used with embedded signer.

To add an embedded signer, the following parameters should be set:

  • workflow.actions[i].mode: must have value embedded.
  • workflow.actions[i].returnUrl: a callback URL where signature result will be sent.
  • workflow.actions[i].signer.clientUserId: Optional signer identifier which will be added to the signature reason and audit trail.

Once the workflow has been launched, the signing url can be retrieved and redirected to or used as an iframe source.

After signature, the page will be redirected to the returnUrl URL. The status will be appended as a query parameter (?status=) with the following values possible: success, failure, expired.


Signature Zones

A zone is defined within the workflow.documents[i] property. It can host a signature or a text field. Each zone is associated with a document (either by embedding the document directly or using the documentId reference)

In case of remote signers, it is not mandatory to define signature zones to create a project. It is mandatory to launch it however. If zones are not known in advance, project initiator should be redirected to project workspace to complete this step (see Redirection URL).

There are two ways to define a signature zone: either by seeting the zone coordinates or by defining anchors where to apply the zone.


Using x,y coordinate:

To define coordinate, use the array fields (workflow.documents[i].fields[j]) to set its position (x,y,width,height, page) as well as a reference to a given signer.


How to set the coordinates of the zone?

ConsignO Cloud uses the term "units" as a unit length. 1 unit = 1 / 72". Origin is in the top left corner of the document.

To define the location of the zone:

  • Convert your PDF document size in units. Ex.: A 8.5" x 11" (letter format) will be 612 x 792 units.

  • Based on the location of the zone, derive the right coordinates.

  • By default, size of the signature zone is set to width = 165 and height = 37.

  • To use non-default and variable value, manual configuration is needed in your profile (contact Notarius).


Using anchors as a placeholder:

An anchor is a reference within the document that will indicate where to apply a signature. It is a text tag, present within the document, that typically would be of the same color of the document background (white on white). This text can't be seen by a human eye, but can be detected by the platform and be used as a placeholder to apply the signature.

To define anchors, use the array fields (workflow.documents[i].anchors[j]).

If a tag has many occurrences within a document, it will be used as often as found, unless page restrictions are set.

Tag must be different from any word within the document. It is recommended to use square or curly brackets to make it unique.


Signer Details

Signer details are defined within the workflow.actions[i].signer property.

This signer parameter is used to set the signer information (firstName, lastName, email, etc.) including which authentication methods should be used and language for communication.

A signer is either one of the following three types: esig (for electronic signature), certifio (for signing using Certifio certificate) or freezone (for text zone only).

A given signer is associated to a given zone by defining a common random numerical value to the workflow.documents[i].fields[j].assignedTo parameter and to the workflow.actions[i].signer.ref parameter.

In case of remote signers, it is not mandatory to define signers to create a project. It is mandatory to launch it however. If signers are not known in advance, project initiator should be redirected to project workspace to complete this step (refer to Redirection URL section).

If signer is not know, properties workflow.actions[i].signers[j].role should be defined as well as workflow.actions[i].signers[j].placeHolder


Authentication Method Reference (AMR)

Four AMR are currently supported: link, sms, call or secret.

Link is always needed as it refers to the email being sent with URL to remote signer or the returnUrl in case of embedded signer.

For SMS and Call, the phone number assigned to the signer or contact will be used to share the code to be entered.

For AMR Secret, you must define properties secretQuestion, secretAnwser and isSecretAnswerChanged. Secret is not supported in Embedded Signing mode.

By default, two factors must be defined. Upon request, it is possible to deactivate the second one (Contact Notarius). Supported AMR can be set at the organisation level.


Signature Sequence

If there are multiple signers for a given workflow, it is possible to allow signatures to happen in parallel or to force all or some of them to happen in sequence.

Parallel signers can be grouped together using the workflow.actions[i].step . All signers sharing same step will be allowed to sign in parallel.

If omitted, signers will be requested to complete their action per the defined order within the workflow.

If two or more steps are defined within a workflow, the steps will be done in sequence. Signers with same step will sign in parallel.


Redirection URL

  • Use editUrl parameter part of the /workflows response to redirect user to the project creation workspace.
  • Set workflow.returnUrl property to define return URL once previous step is completed.
  • Status is appended in the returnUrl, for example: https://my.return.url/?status=success. The status can cover to workflow or the signature, if the project initiator was set as a signer.

    Possible workflow status:

    • WORKFLOW_UPDATED
    • WORKFLOW_LAUNCHED
    • WORKFLOW_CANCELED
    • SIGNATURE_SUCCESS
    • SIGNATURE_CANCELLED
    • SIGNATURE_DECLINE
  • Set workflow.actions[i].returnUrl property to define return URL once signature is completed in Embedded signer mode
  • Status is appended in the returnUrl, for example: https://my.return.url/?status=success.

    Possible signature status:

    • success
    • decline


Notifications

Person to Notify

When launching a project, it is possible to define a person to be notified at project completion. This person will receive a link to download the final version of the documentation.

This can be set using the workflow.notifications[i]. property. Authentication factor and associated parameters must be defined when applicable based on the tenant.


Email notification to project initiator

Email notification to project initiator can be enable or disable by using the workflow.workflowOwnerEmailsEnabled property to either true or false.

When no webhook is set, it is set to true by default. When webhook is set, it is set to false by default.

This email refers to email sent to owner at project completion and when a given signature step is completed.

post

Creates a new workflow. A new workflow is created from an uploaded document. A workflow defines various actions to be done on the document.

get

Retrieves a specific workflow

delete

Deletes a specific workflow

post

Downloads document(s). WARNING the auth token must be passed as a request parameter for this call.

post

Downloads audit trail report. Workflow must be completed. WARNING the auth token must be passed as a request parameter for this call.