Skip to main content

One swipe or one by one: signing several documents in one request

· 4 min read
Julien Jenoudet
Julien Jenoudet
CEO of IgniSign

Many product flows ask a signer for more than one document at once: an onboarding contract with its data-processing annex, a mandate with a consent form, a set of terms that changed together. With the IgniSign API you can put them all in one signature request. The decision left to the integrating developer is how the signer gets through them: one document at a time, which is now the default for requests with several documents, or every document with a single swipe. This post is about that choice and what it changes in your backend.

What the signer sees​

By default, a standard signature request with more than one document is signed one document at a time. Each swipe signs the document on screen, signed documents are marked in the list, and the signer moves on to the next one. Two shortcuts are there. Sign the N remaining documents together signs the rest with one swipe, after a confirmation that lists them. Finish, shown once at least one document is signed, cancels the documents not signed, also after a confirmation.

If you set signDocumentsTogether: true on the signature request, the signer signs every document with one swipe. In the console, the same setting is Sign all documents with a single swipe under Advanced Settings.

Requests with a single document are not affected: they always take one swipe.

One by one: the documents are separate decisions​

Keep the default when:

  • The documents can stand alone. A user can accept the main contract and leave an optional consent unsigned, and your product can work with that answer.
  • The documents are long or different in kind, and you want the signer to look at each one before signing it.
  • You would rather get a partial result than a request the signer abandons.

What it costs you is backend work, because a request can now end partly signed:

  • A signer's SIGNATURE webhooks can arrive over several swipes and sessions, not together.
  • When a signer chooses Finish with documents unsigned, those documents move to a new signature request, created cancelled. Its initialSignatureRequestId points to the original request, and its cancellation webhook carries no signatureRequestExternalId. Match it on initialSignatureRequestId, not on your own external ID.
  • The original request keeps the signed documents, so its documentIds list gets shorter. It completes once every signer is done, and its proofs cover those documents only.
  • In embedded mode, handleSignatureSessionFinalized in @ignisign/ignisign-js is called once per signer, after their last document or after Finish, not after each document.

One swipe: the documents only make sense together​

Set signDocumentsTogether: true when:

  • The documents form one agreement. A contract without its annex is not something your product can act on.
  • Your downstream logic expects all or nothing, and you do not want to model a partly signed state.
  • The set is short, and the signer already reviewed it earlier in your flow.

What it costs you: the signer cannot sign part of the set. If one document is a problem, nothing gets signed, and your flow handles that as a whole.

One practical limit: signature requests created with one-call-sign cannot set this option yet. You set it with updateSignatureRequest (typed in @ignisign/public and @ignisign/sdk 4.3.0), or in the console.

A third option: split the request​

When some documents are required and others are optional, you can also create separate signature requests: one for the required set, signed with a single swipe, and one for each optional document. Each request then has its own status, webhooks and proof, which is often easier to map onto your own records than a request whose document list can shrink. The cost is more requests to create and to track.

A three-question test​

  1. Can your product act on part of the documents being signed? Keep one by one, and handle the partial path.
  2. Do the documents only make sense together? Set signDocumentsTogether: true.
  3. Is it a mix of required and optional documents? Split them into separate signature requests.

Whatever you choose, run the whole path in your development environment first, including a signer who presses Finish halfway through, and check that your webhook handler links the cancelled request back to the original one.