Sending Methods

The Legalesign API provides several ways to send documents for signing. Each method suits a different use case. All methods are asynchronous — they return an ID immediately and process the document in the background.

Quick Comparison

Method	Use case	Documents	API calls
send	Send one document to one or more recipients	1	1
sendBatch	Send multiple different documents as a group	Many	3+ (create → add docs → start)
sendBulk	Send the same template to many different recipients	Many	3+ (start → queue docs → send)
createTask	Run async tasks like reports	N/A	1

send — Single Document

The simplest and most common method. One API call sends one document to one or more recipients.

mutation {
  send(input: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Employment Contract"
    recipients: [
      { firstName: "Jane", lastName: "Smith", email: "jane@example.com", role: "Signer" }
    ]
  })
}

When to use: Most integrations. Sending a contract, NDA, or any single document. If you need to send documents one at a time from your application, this is the right choice.

Returns: A task ID. Poll with the task query to check completion.

See: send reference · DocumentSendSettingsInput

sendBatch — Multiple Documents as a Group

Sends multiple different documents that are logically related (e.g. an employment pack with a contract, NDA, and handbook acknowledgement). The documents are grouped into a Batch and can be sent in a specific order.

The workflow requires three steps:

# Step 1: Create the batch
mutation { sendBatch(input: { groupId: "Z3JwMTIzNDU2", batchName: "New Hire Pack" }) }
# Returns: batchId

# Step 2: Add documents to the batch (repeat for each document)
mutation { sendBatchDocument(input: {
  batchId: "<batchId>",
  sendOrder: 1,
  document: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Employment Contract"
    recipients: [{ firstName: "Jane", lastName: "Smith", email: "jane@example.com", role: "Signer" }]
  }
}) }

# Step 3: Start the batch
mutation { startBatch(input: { batchId: "<batchId>", groupId: "Z3JwMTIzNDU2" }) }

When to use: Sending multiple related documents to the same person or group of people. The enforceOrder flag controls whether documents must be signed sequentially or can be signed in any order.

See: sendBatch · sendBatchDocument · startBatch · Batch type

sendBulk — Same Template to Many Recipients

Sends the same template to many different recipients in parallel. Useful for mass mailings like annual policy renewals or compliance acknowledgements.

The workflow:

# Step 1: Create the bulk task
mutation { startBulk(input: { groupId: "Z3JwMTIzNDU2", name: "Annual Policy Renewal" }) }
# Returns: bulkId

# Step 2: Queue documents (repeat for each recipient)
mutation { addBulkDocument(input: {
  bulkId: "<bulkId>",
  document: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Policy Renewal - John Doe"
    recipients: [{ firstName: "John", lastName: "Doe", email: "john@example.com", role: "Signer" }]
  }
}) }

# Step 3: Send all queued documents
mutation { sendBulk(input: { groupId: "Z3JwMTIzNDU2", bulkId: "<bulkId>", name: "Annual Policy Renewal" }) }

When to use: Sending the same document to hundreds or thousands of different people. More efficient than calling send in a loop because the platform processes the queue in parallel.

See: startBulk · addBulkDocument · sendBulk

createTask — Async Tasks

Not a sending method, but related. createTask triggers asynchronous operations like generating reports. The task system is the same one that powers send — both return a task ID you can poll.

mutation {
  createTask(input: {
    groupId: "Z3JwMTIzNDU2"
    title: "Audit Report"
    status: DRAFT
  }) {
    id
    status
  }
}

See: createTask · TaskStatus

Choosing the Right Method

Need to send one document?
  → use send

Need to send multiple different documents as a package?
  → use sendBatch

Need to send the same template to many people?
  → use sendBulk

Just need one or two documents sent from your app?
  → use send (even if you call it multiple times)

Most integrations only need send. Use sendBatch and sendBulk when you have a specific workflow that requires grouping or mass sending.

Notification Options

Both sendBatch and sendBulk accept notification flags that control email behaviour:

Flag	Description
enforceOrder	Documents must be signed in the specified sendOrder
notifySender	Email the sender when each document is signed
notifySenderAttach	Attach the signed PDF to the sender notification
notifyParticipants	Email participants when the document is complete
notifyParticipantsAttach	Attach the signed PDF to participant notifications

The send mutation inherits these settings from the group's Experience configuration.