Skip to main content

One request or one per signer: when several people sign in your flow

· 4 min read
IgniSign Team
IgniSign Team

Sooner or later a flow in your product needs more than one signer. A lease needs the tenant and the landlord. An onboarding document goes to every new hire in a team. A policy update goes to each account admin. With the IgniSign API you list the signers on the signature request, and then you face one decision: should those people share one request, or should each of them get a request of their own?

Two shapes for the same list of signers​

Shared request. You create the request with several signers, either through the one-call signature request or by initializing a request and setting its signerIds. Every signer signs the same documents in the same request. The signed PDF's signature page summarises everyone who signed, and your backend follows one signatureRequestId.

One request per signer. You set individualizeRequests: true on the request. IgniSign then gives each signer a separate signature request, and the original request is marked CHILDREN_GENERATED. Each child request carries initialSignatureRequestId, the id of the request it came from. If you named approvers, they are included in each child request. In the console, the same setting reads Create one request per signer.

Same input, same list of signers. What changes is what "done" means, and what your backend stores.

Choose a shared request when the signatures belong together​

Pick the shared shape when the document only makes sense once every party has signed it:

  • a contract between your customer and one of their clients;
  • a mandate that two account holders sign jointly;
  • an agreement that adds a co-signer or a guarantor.

Your business record has one state, and one request maps to it cleanly. Store the signatureRequestId, or your own externalId, on that record, wait for the request to complete, then fetch the proof for each document.

One detail matters here. IgniSign sends CANCELLED and EXPIRED only when no one has signed. If at least one signer signed before the request expired or was cancelled, your endpoint receives COMPLETED. So for a shared request, COMPLETED on its own does not mean that everyone signed. Before you mark the contract as fully signed in your product, compare the request's signerIds with its signedBy list (the signature request context returns both), or count the SIGNATURE events with the action FINALIZED, which carry the signer id.

Choose one request per signer when each signature stands alone​

Pick individual requests when the same document goes to many people and each signature is its own fact:

  • a policy acknowledgement from every user of a workspace;
  • an onboarding document that each new hire signs;
  • a consent that each participant gives for themselves.

Here a shared request would couple people who have nothing to do with each other. One person who never opens the document would keep the whole request open, and the signature page would list colleagues who only happened to be invited the same day. With one request per signer, each request completes on its own, and each proof covers one signer.

The cost is mapping. Your backend now tracks several requests for one action in your product. Keep the original signatureRequestId on your record, and use the initialSignatureRequestId that comes with signature request webhook events to group the children under it. Then tie each child to your user through its signer id. A dashboard that shows "12 of 15 signed" reads straight from that grouping.

In an embedded flow​

Embedded mode works with both shapes. When a request launches, the LAUNCHED webhook lists its signers, each with the token your front end uses to open that signer's session in your iframe. With a shared request, one event gives you every token for the same request id. With one request per signer, each token belongs to a child request, so open each session against the request id the token came with, not the original one.

A short rule​

Ask one question about the document: is it finished when everyone has signed, or each time someone signs?

  • Everyone: one shared request, and check signedBy before you treat it as fully signed.
  • Each time: set individualizeRequests, and group the children by initialSignatureRequestId.

The setting lives on the request, so you choose it per flow. A single product can run joint contracts as shared requests and team-wide acknowledgements as one request per signer, on the same integration.