This guide walks you through sending the same document to a large group of recipients using the NSE Bulk Envelope API. By the end you will have created a bulk envelope, uploaded a document, defined a bulk signing stage for the mass recipients, added a second stage for a standard (non-bulk) recipient, placed signature fields for both, and sent the bulk envelope.
A bulk envelope is useful when the same document (for example a campaign contract or a policy acknowledgement) must be sent individually to many recipients, while optionally still going through one or more fixed, non-bulk approvers or signers.
- A valid JWT Bearer token or Personal Access Token
- Your organization ID (
organizationId) - A document ready to upload
Start by creating the bulk envelope. Like a regular envelope, it is created in draft status and stays editable until you send it.
POST /api/v1/organizations/{organizationId}/bulk-envelopes{
"name": "Bulk contract for Q1 campaign",
"expiration": {
"mode": "Absolute",
"expiresAt": "2026-08-15T06:20:36.459164+00:00"
}
}Response 201 Created
{
"id": "b7e2a9c0-1234-1234-1234-1c7e5f8a3d21"
}Save the returned id — this is your bulkEnvelopeId for every subsequent call.
Upload the PDF that will be sent to every recipient. This endpoint uses multipart/form-data, not JSON.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files
Content-Type: multipart/form-data| Field | Type | Description |
|---|---|---|
file | binary | The PDF file to attach |
Response 201 Created
{
"id": "c4f81b3d-1234-1234-1234-2d9f4c1b6a05"
}Save the returned id — this is your fileId, used when placing signature fields.
Create the stage that will hold the mass recipients. Setting mode to Bulk tells the system that recipients added to this stage will each receive their own copy of the envelope, signed independently.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages{
"name": "Bulk Stage",
"requiredRecipientCompletions": 1,
"type": "Signer",
"mode": "Bulk"
}Response 201 Created
{
"id": "9f534128-1234-1234-1234-ddd212a60d68"
}Save the returned id — this is your bulkStageId.
Add the recipients who will each receive an individual copy of the envelope. Repeat this call once per recipient.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{bulkStageId}/recipientsRecipient 1
{
"languageCode": "en",
"givenName": "John",
"surname": "Doe",
"email": "john.doe@example.com"
}Response 201 Created
{
"id": "01750358-1234-1234-1234-b8ccbd123e79"
}Recipient 2
{
"languageCode": "en",
"givenName": "Jane",
"surname": "Doe",
"email": "jane.doe@example.com"
}Response 201 Created
{
"id": "2b8a6e71-1234-1234-1234-7f3c5d8a2b64"
}In addition to the bulk stage, add a second stage for a standard (non-bulk) recipient — for example an internal approver who must sign every individual envelope generated from the bulk recipients. Because this stage is not marked as bulk, the same recipient is carried over into each of the individual envelopes created for the bulk stage's recipients, and is required to sign on every one of them.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages{
"name": "Standard Stage",
"requiredRecipientCompletions": 1,
"type": "Signer",
"mode": "Standard"
}Response 201 Created
{
"id": "6d3e9a17-1234-1234-1234-8e1b4f7c2a93"
}Save the returned id — this is your standardStageId.
Now add the single recipient for this stage:
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{standardStageId}/recipients{
"languageCode": "en",
"givenName": "Joe",
"surname": "Public",
"email": "joe.public@example.com"
}Response 201 Created
{
"id": "7a1c4e58-1234-1234-1234-1d5b9c3f7e28"
}Save the returned id — this is your standardRecipientId.
Add the fields that should appear on the document for each stage. This call fully replaces all tasks for the file, so send the complete list each time.
A field can be bound to a whole stage (stageId) or to a specific recipient (recipientId):
- Use
stageIdfor the bulk stage — the same field is applied to every recipient added to that stage, each on their own copy of the document. - Use
recipientIdfor the standard stage — the field is bound to that one specific recipient, who signs it on every individual envelope generated from the bulk stage.
PUT /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files/{fileId}/tasks{
"tasks": [
{
"field": {
"fieldType": "Signature",
"id": "signature1",
"page": 1,
"positionX": 100,
"positionY": 200,
"width": 200,
"height": 50,
"required": true,
"allowedSignatureTypes": [
{ "signatureType": "ClickToSignSignature" }
]
},
"stageId": "9f534128-1234-1234-1234-ddd212a60d68",
"sortOrder": 1
},
{
"field": {
"fieldType": "Signature",
"id": "signature2",
"page": 1,
"positionX": 100,
"positionY": 300,
"width": 200,
"height": 50,
"required": true,
"allowedSignatureTypes": [
{ "signatureType": "ClickToSignSignature" }
]
},
"recipientId": "7a1c4e58-1234-1234-1234-1d5b9c3f7e28",
"sortOrder": 1
}
]
}A few things worth noting:
stageIdon a task belonging to a bulk stage means the field is generated on every individual copy created for that stage's recipients — you don't need to repeat the task per bulk recipient.recipientIdon a task pins the field to one specific recipient, typically used for standard, non-bulk stages.positionX/positionYare the coordinates of the field's top-left corner on the page.allowedSignatureTypescontrols which signing methods the recipient can choose. If you leave itnull, the organization defaults apply.sortOrdersets the sequence in which fields are presented to the signer.
Response 204 No Content
Once everything is configured, send the bulk envelope. This generates one individual envelope per bulk recipient, transitions each from draft to sent, and triggers the invitation emails.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/sendNo request body required.
Response 200 OK
{
"id": "b7e2a9c0-1234-1234-1234-1c7e5f8a3d21"
}