Skip to main content

Send a Batch of Documents

A batch groups multiple documents into a single send operation. Each document can go to different recipients and use a different template. You control the order documents are sent and whether signers are notified when earlier documents in the batch complete.

The signing experience for batches is also different from a standard document send. Signers are shown the other documents in the batch as part of their signing flow, giving them visibility of the full set of documents they need to sign. When and whether a signer can act on each document is still controlled by sequentialSigning (the order parties sign within a single document) and enforceOrder (the order documents are released within the batch). See The four batching workflows for a full breakdown of how these two settings combine.

The process is three steps:

  1. Create the batch — get a batch ID
  2. Add documents to the batch — one mutation per document
  3. Start the batch — triggers sending

Prerequisites​

  • A Legalesign account with API access and your authentication credentials (see authenticate)
  • At least one template with roles configured, and its template ID
  • Your group ID

Step 1: Create the Batch​

Call sendBatch to initialise the batch and receive a batch ID. You'll use this ID in every subsequent call.

mutation CreateBatch {
  sendBatch(input: {
    batchName: "August contracts"
    groupId: "Z3JwWW91ckdyb3VwSWQ="
    enforceOrder: true
    notifySender: true
    notifySenderAttach: false
    notifyParticipants: true
    notifyParticipantsAttach: false
  })
}

Response:

{
  "data": {
    "sendBatch": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
  }
}

Save the returned ID — this is your batchId for all subsequent calls.

Key fields:

  • enforceOrder: true — documents are sent in sendOrder sequence; the next document only sends after the previous one completes
  • notifySender / notifyParticipants — control email notifications on completion
  • notifySenderAttach / notifyParticipantsAttach — whether to attach the signed PDF to those notifications

See SendBatchInput for all fields.

Step 2: Add Documents to the Batch​

Call sendBatchDocument once for each document. Use sendOrder to control the sequence (0-indexed).

First document (sendOrder: 0)​

mutation AddDocumentToBatch {
  sendBatchDocument(input: {
    batchId: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
    sendOrder: 0
    document: {
      title: "Service Agreement"
      templateId: "dHBsWW91clRlbXBsYXRlSWQtMDAwMC0wMDAwLTAwMDA="
      groupId: "Z3JwWW91ckdyb3VwSWQ="
      tag: ""
      pdfPassword: ""
      retainPdfPassword: false
      allowPrinting: true
      allowCopying: true
      sequentialSigning: true
      documentCCEmail: []
      senderFields: [
        { id: "ZWxlWW91clNlbmRlckZpZWxkSWQ=", value: "Acme Ltd" }
      ]
      participantFields: [
        { id: "ZWxlUGFydGljaXBhbnRGaWVsZDE=", value: "" }
        { id: "ZWxlUGFydGljaXBhbnRGaWVsZDI=", value: "" }
        { id: "ZWxlUGFydGljaXBhbnRGaWVsZDM=", value: "" }
      ]
      recipients: [
        {
          order: 0
          signerIndex: 1
          roleId: "cm9sWW91clJvbGVJZA=="
          experience: "ZXhwWW91ckV4cGVyaWVuY2VJZA=="
          firstName: "Alex"
          lastName: "Taylor"
          email: "alex.taylor@example.com"
          phoneNumber: ""
          expiryDate: null
          timeZone: "Europe/London"
          skipped: false
        }
      ]
    }
  })
}

Response:

{
  "data": {
    "sendBatchDocument": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
  }
}

The response echoes back the batchId — not a document ID.

Second document (sendOrder: 1)​

Repeat the mutation with a different template, sendOrder: 1, and the same or different recipients:

mutation AddDocumentToBatch {
  sendBatchDocument(input: {
    batchId: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
    sendOrder: 1
    document: {
      title: "Data Processing Agreement"
      templateId: "dHBsWW91clNlY29uZFRlbXBsYXRlSWQ="
      groupId: "Z3JwWW91ckdyb3VwSWQ="
      tag: ""
      pdfPassword: ""
      retainPdfPassword: false
      allowPrinting: true
      allowCopying: true
      sequentialSigning: true
      documentCCEmail: []
      senderFields: [
        { id: "ZWxlU2VuZGVyRmllbGRBMQ==", value: "" }
        { id: "ZWxlU2VuZGVyRmllbGRBMg==", value: "Acme Ltd" }
      ]
      participantFields: [
        { id: "ZWxlUGFydGljaXBhbnRGaWVsZEEx", value: "" }
        { id: "ZWxlUGFydGljaXBhbnRGaWVsZEEy", value: "" }
        { id: "ZWxlUGFydGljaXBhbnRGaWVsZEEz", value: "" }
      ]
      recipients: [
        {
          order: 0
          signerIndex: 1
          roleId: "cm9sU2Vjb25kUm9sZUlk"
          experience: "ZXhwWW91ckV4cGVyaWVuY2VJZA=="
          firstName: "Alex"
          lastName: "Taylor"
          email: "alex.taylor@example.com"
          phoneNumber: ""
          expiryDate: null
          timeZone: "Europe/London"
          skipped: false
        }
      ]
    }
  })
}

Add as many documents as needed before moving to Step 3.

tip

Each document can use a different template and different recipients. The sendOrder value determines the sequence when enforceOrder is true.

See SendBatchDocumentInput for all fields. The nested document object follows the same validation rules as DocumentSendSettingsInput.

Step 3: Start the Batch​

Once all documents are added, call startBatch to mark the batch as ready. This triggers the send.

mutation StartBatch {
  startBatch(input: {
    batchId: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
    groupId: "Z3JwWW91ckdyb3VwSWQ="
  })
}

Response:

{
  "data": {
    "startBatch": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
  }
}

After startBatch, Legalesign queues the documents. If enforceOrder is true, the first document (sendOrder: 0) is sent immediately and subsequent documents are held until the previous one completes.

Tracking Batch Progress​

Batches also have their own dedicated view in the Legalesign web app, giving you a consolidated overview of all documents in the batch and their signing status — useful for monitoring progress without querying the API.

To query batch status programmatically, use the batch ID:

query GetBatch {
  batch(id: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw") {
    id
    status
    documents {
      edges {
        node {
          id
          title
          status
        }
      }
    }
  }
}

You can also use subscriptions to receive real-time updates — see Track Document and Recipient Lifecycle with Subscriptions.

Export This Article

Save a copy of this page as PDF or plain text.