eID Easy Docs

Document Signing Reason Implementation

In some cases, you might want to ensure the end signer understands why the document is being signed and what is being consented to.

This is especially important when signing documents that are legally binding or have significant consequences. By providing a clear reason for signing, you can help ensure that the signer is fully aware of the implications of their action and can make an informed decision.

eID Easy offers a built-in reason field for signing documents that can be used to verify the signer's consent. When a user consents to signing, the reason is automatically saved in the document metadata. For PDF documents, if the signing method supports visual signatures, the reason will be displayed on the document.

Exact integration steps will depend on the specific integration method you are using with eID Easy.

The first step is the same regardless of the integration method

To start using a signing reason, simply add the signing_reason parameter to your Prepare the file for signingopen in new window API request.

For example, POST https://id.eideasy.com/api/signatures/prepare-files-for-signing:

{
    ...
    "signing_reason": "I agree to the terms and conditions of the contract",
    ...
}

If you are using our signing page or widget to handle UI interactions

We will handle the signing reason with no additional configuration required.

If you are using our API directly and handle UI interactions yourself

Before showing available signing methods to the user, make a request to the "get signing document status" API endpoint to see if a signing reason is already set and what the latest status is. POST https://id.eideasy.com//api/signatures/signing-session/status with payload:

{
  "client_id" : "your client_id",
  "doc_id": "doc ID from prepare-files-for-signing response"
}

The example response will contain the signing reason if it's already set:

{
  "signing_session_status": "OPEN",
  "signing_session_user_status": null,
  "signing_reason": {
    "reason_text": "I agree to the terms and conditions of the contract",
    "accepted_at": null, // timestamp of the last user consent
    "accepted_in_current_session": false // shows if current signer who is signing the document has already consented to signing reason
  },
  "require_signing_reason": true
}

If accepted_at is null, show the user a form to enter the signing reason exactly as provided in the response.signing_reason.reason_text. When the user types in the reason and submits the form, make another request to validate the signer's consent: POST https://id.eideasy.com/api/signatures/signing-session/reason/accept with payload:

{
  "client_id" : "your client_id",
  "doc_id": "doc ID from prepare-files-for-signing response",
  "reason_text": "{{signed input goes here}}"
}

When the user's consent 100% matches the expected reason, the API will return a 200 OK response and {"status":"OK"} in the response body.

Nothing else is required to start using the signing reason. The user's consent will be visible on the visual signature of the document and in the document metadata. Currently, we support signing reasons for PDF documents and ASiC-e containers.

Last Updated: