Skip to main content

Optional documents

A participant can reject a document instead of signing or approving it. By default, a rejected document rejects the whole Flow process. You can make a document optional. Then the participant can reject it, and the Flow process continues with the other documents.

Rejection behavior​

The sign and approve steps have an if_rejected property. It holds the step that Flow evaluates when the participant rejects one of the documents of the step. After Flow evaluates the if_rejected step, the process continues as if the participant signed or approved the rejected document.

Flow evaluates the if_rejected step once for each rejected document. If the participant rejects two documents of the same step, Flow evaluates it twice.

If you do not set if_rejected, Flow defaults to the reject_instance step. This step rejects the whole Flow process:

{
  "type": "sign",
  "participant": "alice",
  "documents": ["agreement"],
  "if_rejected": { "type": "reject_instance" }
}

Making a document optional​

To make a document optional, set if_rejected to the empty step. Flow then ignores the rejection and continues the process.

In the example below, Alice must sign agreement, but she can reject newsletter_consent. The two documents are in different sign steps, so each step has its own rejection behavior:

{
  "type": "sequence",
  "steps": [
    {
      "type": "sign",
      "participant": "alice",
      "documents": ["agreement"]
    },
    {
      "type": "sign",
      "participant": "alice",
      "documents": ["newsletter_consent"],
      "if_rejected": { "type": "empty" }
    }
  ]
}

The if_rejected property applies to all the documents in its step. If a step has more than one document, all of them are optional or none of them are. To mix mandatory and optional documents, put them in different steps. A parallel_all step lets the participant sign them in any order.

Flow does not sign documents from different sign steps together. The participant signs each step separately. If the steps use a sign authentication, the participant authenticates once for each step.

What happens when a participant rejects an optional document​

When a participant rejects an optional document:

  • The document gets the rejected status. Nobody can sign or approve it after that.
  • Later sign and approve steps skip the rejected document.
  • The author of the Flow process gets an email about the rejection. The email includes the reason, if the participant gave one.
  • The participant goes back to their overview page. The page shows the documents that they still must sign. If the participant's party in the document has a reject_redirect_url, the participant goes to that URL instead.
  • The Flow process continues. It can complete with the other documents.

Other rejection behavior​

The if_rejected step can also contain other steps. For example, it can send a custom callback with a callback step, or send a message to a participant with a send_email or send_sms step. These steps send their standard invitation, confirmation, or access link message. To write your own text in the message property, your account must have custom email or SMS texts enabled.

The sign, approve, redirect, seal, show_attachments, and request_attachment steps cannot be a part of if_rejected. If you use one of them, the Create Instance end-point returns an error.