Reusable Workflows

Reusable workflows pin templates, participant roles, signing methods, e-stamping, notifications, and optional internal approval into a versioned execution policy. Use them when callers should supply only recipients and variable field values.

Lifecycle

1. POST /workflows creates a definition and version 1 draft.
2. PATCH /workflows/{workflowId} edits the current draft. Editing a workflow after publication creates a new draft version.
3. POST /workflows/{workflowId}/publish validates its templates and makes the draft immutable. The previously published version is archived.
4. POST /workflows/{workflowId}/runs always launches the latest published version and returns the created envelope plus its approval state.

The API key needs workflows:read for list/get and workflows:write for create, update, publish, and run.

const workflow = await client.workflows.create({
  name: "NDA approval",
  config: {
    documents: [{ templateId: "tpl_123", label: "NDA" }],
    participants: [{
      key: "signer",
      label: "Signer",
      order: 1,
      signatureMethod: "electronic",
    }],
    execution: { mode: "sequential", emailNotifications: "all" },
    approvalStages: [],
  },
});

await client.workflows.publish(workflow.definition.id);
const run = await client.workflows.run(workflow.definition.id, {
  title: "NDA — Acme",
  recipients: [{
    participantKey: "signer",
    name: "Asha Rao",
    email: "asha@example.com",
  }],
  idempotencyKey: "nda-acme-2026-07",
});

idempotencyKey on a single run is accepted by the public contract. Bulk runs require one and deduplicate per API-key user.

Bulk runs

Queue structured rows with POST /workflows/{workflowId}/bulk-runs, or send CSV text with POST /workflows/{workflowId}/bulk-runs/csv. Both require a published workflowVersionId, bulkSend:write, and enough estimated credits.

CSV validation is all-or-nothing:

• 202 means every row validated and the returned job was queued.
• 422 returns accepted: false, detected headers, and row/column errors. No job is created and no credits are consumed.

Poll GET /bulk-jobs/{jobId} for counters and row results. A job can be cancelled only while validating or queued. POST /bulk-jobs/{jobId}/retry-failed requeues failed rows with fewer than three attempts. Download failures from GET /bulk-jobs/{jobId}/errors.csv.

const job = await client.workflows.createBulkRun(workflowId, {
  workflowVersionId: "wv_123",
  idempotencyKey: "july-nda-batch",
  rows: [{
    rowNumber: 1,
    title: "NDA — Acme",
    recipients: [{
      participantKey: "signer",
      name: "Asha Rao",
      email: "asha@example.com",
    }],
  }],
});

const progress = await client.bulkJobs.get(job.id);
if (progress.failedRows > 0) {
  const csv = await client.bulkJobs.downloadErrors(job.id);
}

See the generated endpoint reference below this guide for every request and response field, including e-stamp policy and CSV validation schemas.