Skip to content

Recipients

Recipient routing

Choose sequential routing to have recipients act one at a time in order, or parallel routing to notify every signer at once.

The routing property controls the order in which recipients receive and act on the envelope. Two options are available: sequential and parallel. The default is sequential.

Sequential and parallel routing

Pick a routing, send the envelope, then act as each recipient.

  • sequential: One recipient at a time, in recipients order. Each one must complete before the next is notified. Sam Patel (preparer), Alex Chen (approver) and Jane Doe (signer) end completed.
  • parallel: Every signer gets the request at once and signs in any order. Parallel accepts signer and automatic_signer only, so this example has three signers. Jane Doe (signer), John Smith (signer) and Maria Garcia (signer) end completed.
Every invitation here goes by email. A recipient whose ceremony your app creates also moves to sent, with recipient.sent, once the ceremony is created; until then it stays pending.

Sequential routing

With sequential routing, the envelope is delivered to one recipient at a time, in the order listed in the recipients array. Each recipient must complete their part before the next one is notified.

  • Recipients act in the order defined in the recipients array.
  • Each recipient must complete before the next one is notified.
  • Recipients acting later can see signatures and data entered by those who acted before them.
  • Recipients waiting for a previous recipient will have a status of awaiting.
  • Use this when the order of signatures matters.

Parallel routing

With parallel routing, all recipients receive the envelope at the same time and can act in any order.

  • All recipients are notified simultaneously.
  • Recipients can act in any order.
  • Use this when signing order does not matter.

Parallel routing accepts the recipient types signer and automatic_signer only (qualified signers need sequential routing too). It also rejects input places (text_input, boxed_text_input, checkbox, dropdown and radio_group), even when the envelope has a single recipient. An envelope with an approver, a preparer or an input place needs sequential routing; otherwise the request fails with a validation error.

Setting routing on an envelope

Set the routing property when creating an envelope. If omitted, sequential routing is used.

HTTP
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement",
  "routing": "parallel",
  "documents": [
    {
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
      "places": [
        { "key": "client_signs_here", "type": "signature", "recipient_key": "client" },
        { "key": "provider_signs_here", "type": "signature", "recipient_key": "provider" }
      ]
    }
  ],
  "recipients": [
    { "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane.doe@example.com" },
    { "type": "signer", "key": "provider", "name": "John Smith", "email": "john.smith@example.com" }
  ]
}