From the Trenches: Bulk sending envelopes with custom tabs
See how to set up and run a bulk send operation with the eSignature REST API.
One of the most powerful Docusign tools for streamlining business processes is bulk sending. Bulk sending allows senders to send a standardized document easily to many recipients at once. In this post, I’ll walk you through a real-world example of leveraging the Docusign bulk send feature.
Imagine you're the operations manager at a real estate agency handling multiple property transactions simultaneously. Each transaction requires numerous documents to be signed by various parties, including buyers, sellers, and agents. Traditionally, managing these documents would involve printing, signing, scanning, and emailing or mailing them back and forth—a time-consuming and error-prone process. But with bulk sending, you can upload a list of recipients and documents, and the platform takes care of sending the documents to each recipient for signature. This significantly reduces the time and effort required to distribute documents individually.
And what if each recipient requires different information to be filled out, checked, or signed on the documents? This is where custom tabs come into play: that is, adding custom tabs, such as text tabs, radio groups, or signature tabs, to your documents. These tabs can be specified per recipient, ensuring that each party sees only the relevant fields they need to complete an agreement.
Bulk sending with the eSignature REST API
Here’s how to use a REST API to send an envelope to numerous recipients in bulk.
Call the createBulkSendList method with custom tabs: This method allows you to generate a bulk send list, enabling you to send an envelope to multiple recipients simultaneously. By leveraging this list, you can distribute agreements to different signers, customizing the visibility of access and actions for each signer as needed. Here’s the endpoint to call and an example JSON method body:
POST https://demo.docusign.net/restapi/v2.1/accounts/{accountId}//bulk_send_lists{ "bulkCopies": [ { "emailSubject": "Agreement", "emailBlurb": "ContractAgreement", "recipients": [ { "customFields": [ "BuyerDetails" ], "deliveryMethod": "email", "email": "Buyer@gmail.com", "idCheckConfigurationName": "SMS Auth $", "identificationMethod": "phoneauthentication", "identityVerification": { "inputOptions": [ { "name": "Buyer", "phoneNumberList": [ { "countryCode": "", "number": "" } ] } ], "workflowId": "c368e411-xxxx-xxxx-xxxx-dca94ac539ae" }, "recipientId": "1", "signerName": "Buyer", "name": "buyer_name", "smsAuthentication": { "senderProvidedNumbers": [ "" ] }, "signers": [ { "name": "LUBNA BAROLDY (Buyer)", "email": "buyer@example.com", "recipientId": "1", "routingOrder": "1", "roleName": "Buyer", "tabs": { "signHereTabs": [ { "name": "SignHere", "tabLabel": "buyerSignature", "documentId": "1", "recipientId": "1", "pageNumber": "1", "xPosition": "109", "yPosition": "225" } ], "fullNameTabs": [ { "name": "BuyerFullName", "font": "lucidaconsole", "documentId": "1", "recipientId": "1", "pageNumber": "1", "xPosition": "59", "yPosition": "236" } ], "radioGroupTabs": [ { "documentId": "1", "groupName": "BuyerChoice", "radios": [ { "anchorString": "RadioGroup1", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-10", "value": "Yes" }, { "anchorString": "RadioGroup1", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-15", "value": "No" } ] } ], "textTabs": [ { "anchorString": "TextTab", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-5", "width": "50", "conditionalParentLabel": "buyerChoice", "conditionalParentValue": "Yes", "documentId": "1" } ] } } ] }, { "customFields": [ "sellerddetails" ], "deliveryMethod": "email", "email": "SELLER@gmail.com", "embeddedRecipientStartURL": "https://www.google.com", "idCheckConfigurationName": "+", "identificationMethod": "", "identityVerification": { "inputOptions": [ { "name": "seller", "phoneNumberList": [ { "countryCode": "", "number": "" } ] } ], "workflowId": "c368e411-xxxx-xxxx-xxxx-dca94ac539ae" }, "recipientId": "2", "signerName": "seller", "name": "seller_name", "smsAuthentication": { "senderProvidedNumbers": [ "" ] }, "signers": [ { "name": "Seller Signer Name", "email": "seller@example.com", "recipientId": "2", "routingOrder": "2", "roleName": "Seller", "tabs": { "signHereTabs": [ { "name": "SignHere", "tabLabel": "sellerSignature", "documentId": "4", "recipientId": "2", "pageNumber": "6", "xPosition": "109", "yPosition": "225" } ], "fullNameTabs": [ { "name": "FullName", "tabLabel": "sellerFullName", "font": "lucidaconsole", "documentId": "4", "recipientId": "2", "pageNumber": "6", "xPosition": "59", "yPosition": "236" } ], "radioGroupTabs": [ { "documentId": "4", "groupName": "sellerChoice", "radios": [ { "anchorString": "RadioGroup1", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-10", "value": "Yes" }, { "anchorString": "RadioGroup1", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-5", "value": "No" } ] } ], "textTabs": [ { "anchorString": "TextTab", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-5", "width": "50", "conditionalParentLabel": "sellerChoice", "conditionalParentValue": "Accept", "documentId": "4" } ] } } ] }, { "customFields": [ "agentdetails" ], "deliveryMethod": "email", "email": "AGENT@gmail.com", "embeddedRecipientStartURL": "https://www.google.com", "idCheckConfigurationName": "SMS Auth $", "identificationMethod": "phoneauthentication", "identityVerification": { "inputOptions": [ { "name": "agent", "phoneNumberList": [ { "countryCode": "", "number": "" } ] } ], "workflowId": "c368e411-xxxx-xxxx-xxxx-dca94ac539ae" }, "recipientId": "3", "signerName": "agent", "name": "agent_name", "smsAuthentication": { "senderProvidedNumbers": [ "" ] }, "signers": [ { "name": "Agent Name", "email": "Agent@example.com", "recipientId": "3", "routingOrder": "3", "roleName": "Agent", "tabs": { "signHereTabs": [ { "stampType": "signature", "isSealSignTab": false, "name": "SignHere", "tabLabel": "AgentSignature", "documentId": "7", "recipientId": "3", "pageNumber": "8", "xPosition": "109", "yPosition": "225" } ], "fullNameTabs": [ { "name": "FullName", "tabLabel": "AgentFullName", "font": "lucidaconsole", "documentId": "7", "recipientId": "3", "pageNumber": "8", "xPosition": "59", "yPosition": "236" } ], "radioGroupTabs": [ { "documentId": "7", "groupName": "AgentChoice", "radios": [ { "anchorString": "RadioGroup1", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-10", "value": "Yes" }, { "anchorString": "RadioGroup1", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-5", "value": "No" } ] } ], "textTabs": [ { "anchorString": "TextTab", "anchorHorizontalAlignment": "right", "anchorUnits": "pixels", "anchorYOffset": "-5", "width": "50", "conditionalParentLabel": "AgentChoice", "conditionalParentValue": "Accept", "documentId": "7" } ] } } ] } ] } ], "name": "Saibulksendlist" }Once the bulk send list is created, you then obtain a unique bulk send list ID. This ID enables you to send bulk envelopes using the specified list along with the envelope or template ID you are referencing.
Call the createBulkSendRequest method to send the envelopes to your recipient list: This method executes the bulk send. Bulk sending can also be executed in Docusign eSignature by uploading a CSV file containing the necessary information for your recipients, but the API method, as you can see, allows for customizing tabs for each recipient in a way that the UI doesn’t. Here’s the endpoint path and its JSON body:
POST /restapi/v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}/send{ "envelopeOrTemplateId": "abd6e7c6-xxxx-xxxx-xxxx-60874d552eda", "batchName": "RentalAgreementBatches" }
Handling errors
Regardless of whether you use the eSignature UI or the eSignature API, certain common errors can arise. When using CSV uploads, you may encounter messages indicating errors within your bulk lists. On the other hand, using the API, you might face errors related to mismatches between custom fields specified in your template or envelope and those in the bulk send list. It's crucial to ensure that the tabs in the bulk list always correspond correctly to the original envelope or template intended for sending.
For more information about setting up your bulk list for bulk sending, check our Signing Groups FAQ.
Additional resources
Sai Dandamudi has been with Docusign since 2022. Her work is focused in helping developers resolve issues they encounter when developing applications using Docusign APIs and advising developers on how to integrate with Docusign APIs and SDKs by consulting on best practices and providing code examples. You can reach out to Sai through Linkedin.
Related posts
Discover what's new with Docusign IAM or start with eSignature for free
