{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/namirialsignenterprise/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Send a Bulk Envelope","description":"Integration and usage documentation."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"send-a-bulk-envelope","__idx":0},"children":["Send a Bulk Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A valid ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JWT Bearer token"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Personal Access Token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["organization ID"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organizationId"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A document ready to upload"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1--create-a-bulk-envelope","__idx":2},"children":["Step 1 — Create a Bulk Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start by creating the bulk envelope. Like a regular envelope, it is created in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," status and stays editable until you send it."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/bulk-envelopes\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Bulk contract for Q1 campaign\",\n  \"expiration\": {\n    \"mode\": \"Absolute\",\n    \"expiresAt\": \"2026-08-15T06:20:36.459164+00:00\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"b7e2a9c0-1234-1234-1234-1c7e5f8a3d21\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bulkEnvelopeId"]}," for every subsequent call."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2--upload-a-document","__idx":3},"children":["Step 2 — Upload a Document"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload the PDF that will be sent to every recipient. This endpoint uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]},", not JSON."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files\nContent-Type: multipart/form-data\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["binary"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The PDF file to attach"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"c4f81b3d-1234-1234-1234-2d9f4c1b6a05\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileId"]},", used when placing signature fields."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3--add-the-bulk-signing-stage","__idx":4},"children":["Step 3 — Add the Bulk Signing Stage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the stage that will hold the mass recipients. Setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bulk"]}," tells the system that recipients added to this stage will each receive their own copy of the envelope, signed independently."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Bulk Stage\",\n  \"requiredRecipientCompletions\": 1,\n  \"type\": \"Signer\",\n  \"mode\": \"Bulk\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"9f534128-1234-1234-1234-ddd212a60d68\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bulkStageId"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4--add-the-bulk-recipients","__idx":5},"children":["Step 4 — Add the Bulk Recipients"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the recipients who will each receive an individual copy of the envelope. Repeat this call once per recipient."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{bulkStageId}/recipients\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recipient 1"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"languageCode\": \"en\",\n  \"givenName\": \"John\",\n  \"surname\": \"Doe\",\n  \"email\": \"john.doe@example.com\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"01750358-1234-1234-1234-b8ccbd123e79\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recipient 2"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"languageCode\": \"en\",\n  \"givenName\": \"Jane\",\n  \"surname\": \"Doe\",\n  \"email\": \"jane.doe@example.com\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"2b8a6e71-1234-1234-1234-7f3c5d8a2b64\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5--add-the-standard-stage-optional","__idx":6},"children":["Step 5 — Add the Standard Stage (optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Standard Stage\",\n  \"requiredRecipientCompletions\": 1,\n  \"type\": \"Signer\",\n  \"mode\": \"Standard\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"6d3e9a17-1234-1234-1234-8e1b4f7c2a93\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standardStageId"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now add the single recipient for this stage:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{standardStageId}/recipients\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"languageCode\": \"en\",\n  \"givenName\": \"Joe\",\n  \"surname\": \"Public\",\n  \"email\": \"joe.public@example.com\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"7a1c4e58-1234-1234-1234-1d5b9c3f7e28\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["standardRecipientId"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6--place-signature-fields-optional","__idx":7},"children":["Step 6 — Place Signature Fields (optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A field can be bound to a whole stage (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stageId"]},") or to a specific recipient (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]},"):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stageId"]}," for the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["bulk stage"]}," — the same field is applied to every recipient added to that stage, each on their own copy of the document."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]}," for the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["standard stage"]}," — the field is bound to that one specific recipient, who signs it on every individual envelope generated from the bulk stage."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PUT /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files/{fileId}/tasks\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"tasks\": [\n    {\n      \"field\": {\n        \"fieldType\": \"Signature\",\n        \"id\": \"signature1\",\n        \"page\": 1,\n        \"positionX\": 100,\n        \"positionY\": 200,\n        \"width\": 200,\n        \"height\": 50,\n        \"required\": true,\n        \"allowedSignatureTypes\": [\n          { \"signatureType\": \"ClickToSignSignature\" }\n        ]\n      },\n      \"stageId\": \"9f534128-1234-1234-1234-ddd212a60d68\",\n      \"sortOrder\": 1\n    },\n    {\n      \"field\": {\n        \"fieldType\": \"Signature\",\n        \"id\": \"signature2\",\n        \"page\": 1,\n        \"positionX\": 100,\n        \"positionY\": 300,\n        \"width\": 200,\n        \"height\": 50,\n        \"required\": true,\n        \"allowedSignatureTypes\": [\n          { \"signatureType\": \"ClickToSignSignature\" }\n        ]\n      },\n      \"recipientId\": \"7a1c4e58-1234-1234-1234-1d5b9c3f7e28\",\n      \"sortOrder\": 1\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A few things worth noting:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stageId"]}," on a task belonging to a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]}," on a task pins the field to one specific recipient, typically used for standard, non-bulk stages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["positionX"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["positionY"]}," are the coordinates of the field's top-left corner on the page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedSignatureTypes"]}," controls which signing methods the recipient can choose. If you leave it ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", the organization defaults apply."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortOrder"]}," sets the sequence in which fields are presented to the signer."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-7--send-the-bulk-envelope","__idx":8},"children":["Step 7 — Send the Bulk Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once everything is configured, send the bulk envelope. This generates one individual envelope per bulk recipient, transitions each from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sent"]},", and triggers the invitation emails."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/send\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No request body required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"b7e2a9c0-1234-1234-1234-1c7e5f8a3d21\"\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Send a Bulk Envelope","id":"send-a-bulk-envelope","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1 — Create a Bulk Envelope","id":"step-1--create-a-bulk-envelope","depth":2},{"value":"Step 2 — Upload a Document","id":"step-2--upload-a-document","depth":2},{"value":"Step 3 — Add the Bulk Signing Stage","id":"step-3--add-the-bulk-signing-stage","depth":2},{"value":"Step 4 — Add the Bulk Recipients","id":"step-4--add-the-bulk-recipients","depth":2},{"value":"Step 5 — Add the Standard Stage (optional)","id":"step-5--add-the-standard-stage-optional","depth":2},{"value":"Step 6 — Place Signature Fields (optional)","id":"step-6--place-signature-fields-optional","depth":2},{"value":"Step 7 — Send the Bulk Envelope","id":"step-7--send-the-bulk-envelope","depth":2}],"frontmatter":{"seo":{"title":"Send a Bulk Envelope"}},"lastModified":"2026-08-06T07:14:28.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/03-developer-documentation/01-api-reference/bulk-envelope-workflow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}