SignatureAPI
Mint Starter Kit

Use Cases

Send Bulk Envelopes

Send multiple personalized envelopes programmatically from a data set

When you need to send the same document to many recipients with personalized details (for example, renewal notices, offer letters, or sales proposals), you can loop through your data set and create one envelope per record. This guide shows how to send bulk envelopes using a DOCX template and dynamic data.

How It Works

SignatureAPI does not yet have a dedicated bulk-send endpoint. Instead, you create one envelope per recipient by calling POST /v1/envelopes for each record in your data set. Each call uses the same DOCX template URL but provides unique data and recipient details.

SignatureAPI applies rate limits to API requests. When sending a large batch, add a short delay between requests (for example, 200ms) to stay within the limit.

Prepare Your Data

Structure your data as an array of records. Each record contains the recipient details and any merge fields your template requires.

const records = [
  {
    name: "Sarah Chen",
    email: "sarah@example.com",
    role: "Senior Engineer",
    start_date: "March 15, 2026"
  },
  {
    name: "James Wilson",
    email: "james@example.com",
    role: "Product Manager",
    start_date: "April 1, 2026"
  },
  {
    name: "Maria Garcia",
    email: "maria@example.com",
    role: "Design Lead",
    start_date: "April 15, 2026"
  }
];

Create Envelopes in a Loop

For each record, send a POST /v1/envelopes request with the record’s data. The template URL stays the same across all requests.

const TEMPLATE_URL = "https://example.com/templates/offer-letter.docx";
const API_KEY = "key_test_...";

for (const record of records) {
  const response = await fetch("https://api.signatureapi.com/v1/envelopes", {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      title: `Offer Letter - ${record.name}`,
      message: "Please review and sign your offer letter.",
      documents: [
        {
          url: TEMPLATE_URL,
          format: "docx",
          data: {
            employee_name: record.name,
            role: record.role,
            start_date: record.start_date
          },
          places: [
            {
              key: "employee_signature",
              type: "signature",
              recipient_key: "employee"
            }
          ]
        }
      ],
      recipients: [
        {
          type: "signer",
          key: "employee",
          name: record.name,
          email: record.email
        }
      ]
    })
  });

  console.log(`Created envelope for ${record.name}: ${response.status}`);

  // Add a delay to respect rate limits
  await new Promise(resolve => setTimeout(resolve, 200));
}

The Envelope Payload

Each iteration sends a request like this:

// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "title": "Offer Letter - Sarah Chen",
  "message": "Please review and sign your offer letter.",
  "documents": [
    {
      "url": "https://example.com/templates/offer-letter.docx",
      "format": "docx",
      "data": {
        "employee_name": "Sarah Chen",
        "role": "Senior Engineer",
        "start_date": "March 15, 2026"
      },
      "places": [
        {
          "key": "employee_signature",
          "type": "signature",
          "recipient_key": "employee"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "employee",
      "name": "Sarah Chen",
      "email": "sarah@example.com"
    }
  ]
}

Track Your Envelopes

Use the metadata property on each envelope to store identifiers from your system (such as a record ID or batch number). This makes it easier to match envelopes back to your data later.

{
  "title": "Offer Letter - Sarah Chen",
  "metadata": {
    "batch_id": "2026-Q1-offers",
    "record_id": "emp_001"
  },
  //...
}

When you receive webhook events, the envelope_metadata property in the event payload reflects these values.

Try It

Try this example in Postman using your test API key to create a free, non-binding test envelope. Test envelopes won’t send emails, but you can review them in your dashboard.

Keep Learning