How to bulk send envelopes

Expanded by eSignature REST API 2.1

This topic demonstrates how to send envelopes in bulk to multiple recipients with the eSignature API. To accomplish the task, you will first create a bulk send recipients list, then create an envelope. From there, you will combine the envelope and bulk list to initiate bulk send.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data element	Description
{API_ACCOUNT_ID}	A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}	A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at https://<domain>/restapi Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
{BULK_LIST_ID}	A GUID value that identifies the bulk list whose data will be retrieved. This value is automatically generated by Docusign when the bulk list is created.
Bulk sending enabled for your account	Your user role needs the bulkSendingEnabled permission set to true in order to send bulk envelopes. To enable this feature, contact your Account Manager or Business Development representative.
Document to be signed	You must provide at least one document to be signed by the signers of this bulk send operation. For this example, you will be sending a base-64 encoded string representing an NDA form.
Document Visibility features set to Off	This how-to requires that Document Visibility be disabled. Disable Document Visibility in the Sending Settings page. Select the Document Visibility drop-down menu to change it to Off, and then click Save.
{ENVELOPE_ID}	A GUID value that identifies a Docusign envelope. This value is automatically generated by Docusign when the envelope is created.

Step 1. Obtain your OAuth token

To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Confidential Authorization Code Grant for guidance on your options to get an Confidential Authorization Code Grant OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API calls. Construct your headers like this, and then save them into a file or variable, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}" \
					'--header' "Accept: application/json, text/plain, */*" \
					'--header' "Content-Type: application/json;charset=UTF-8" \
					'--header' "Accept-Encoding: gzip, deflate, br" \
					'--header' "Accept-Language: en-US,en;q=0.9")

Step 3. Submit a bulk list

Your bulk send recipients list begins as a file you create in comma-separated values (CSV) format, holding information for each recipient. To prepare the list for bulk sending, you need to create a JSON representation of your CSV data and add it to your request body before sending it to the API as follows:

Create a request body specifying your emails, names, and role names (roleName) for each recipient.
With your constructed API headers, send the current request body to the eSignature REST API, but make sure to substitute your API account ID for {API_ACCOUNT_ID}.
Extract the listId from the response as the {BULK_LIST_ID}. You will use it again in future steps.

printf \
'{
	"name": "sample.csv",
	"bulkCopies": [{
		"recipients": [{
			"roleName": "signer",
			"name": "'"${SIGNER1_NAME}"'",
			"email": "'"${SIGNER1_EMAIL}"'"
		},
		{
			"roleName": "cc",
			"name": "'"${CC1_NAME}"'",
			"email": "'"${CC1_EMAIL}"'"
		}],
		"customFields": []
	},
  {
		"recipients": [{
			"roleName": "signer",
			"name": "'"${SIGNER2_NAME}"'",
			"email": "'"${SIGNER2_EMAIL}"'"
		},
		{
			"roleName": "cc",
			"name": "'"${CC2_NAME}"'",
			"email": "'"${CC2_EMAIL}"'"
		}],
		"customFields": []
	}]
}	
' >> $request_data					
					
# Make a POST call to the bulk_send_lists endpoint, this will be referenced in future API calls.
# Display the JSON structure of the API response
# Create a temporary file to store the response
echo ""
echo "Posting Bulk Send List"
echo ""
response=$(mktemp /tmp/response-bs.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request POST ${base_path}/v2.1/accounts/${account_id}/bulk_send_lists \
     "${Headers[@]}" \
     --data-binary @${request_data} \
     --output ${response})
if [[ "$Status" -gt "201" ]] ; then
    echo ""
	echo "Posting of the Bulk List has failed"
	echo ""
	cat $response
	exit 0
fi
echo ""
echo "Response:"
cat $response
echo ""
#Obtain the BULK_LIST_ID from the JSON response
BULK_LIST_ID=`cat $response | grep listId | sed 's/.*\"listId\":\"//' | sed 's/\",.*//'`

Step 4. Create an envelope

With your generated API headers, create a request body for an envelope and set the envelope status to created. Send a request to the eSignature REST API and extract the envelope ID from the response as the {ENVELOPE_ID}. You will use it again in steps 5 and 6.

request_data=$(mktemp /tmp/request-bs.XXXXXX)
printf \
'{
	"documents": [{
		"documentBase64": "' >> $request_data
		cat $doc1_base64 >> $request_data
		printf '",
		"name": "Lorem Ipsum",
		"fileExtension": "pdf",
		"documentId": "1"
	}],
	"envelopeIdStamping": "true",
	"emailSubject": "Please sign",
	"recipients": {
		"signers": [{
			"name": "Multi Bulk Recipient::signer",
			"email": "multiBulkRecipients-signer@docusign.com",
			"roleName": "signer",
			"routingOrder": "1",
			"recipientId" : "1",
			"recipientType" : "signer",
			"deliveryMethod" : "Email",
			"status": "created",
			"tabs": {
				"signHereTabs": [{
					"documentId": "1",
					"name": "SignHereTab",
					"pageNumber": "1",
					"recipientId": "1",
					"tabLabel": "SignHereTab",
					"xPosition": "200",
					"yPosition": "160"
				}]}
			}],
		"carbonCopies": [{
			"name": "Multi Bulk Recipient::cc",
			"email": "multiBulkRecipients-cc@docusign.com",
			"roleName": "cc",
			"routingOrder": "2",
			"recipientId" : "2",
			"recipientType" : "cc",
			"deliveryMethod" : "Email",
			"status": "created"
			}]
		},		
	"status": "created"
}	
' >> $request_data
echo ""
echo "Creating a draft envelope."
echo ""
response=$(mktemp /tmp/response-bs.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes \
     "${Headers[@]}" \
     --data-binary @${request_data} \
     --output ${response})
#If the Status code returned is greater than 201 (OK / Accepted), display an error message along with the API response. 
if [[ "$Status" -gt "201" ]] ; then
    echo ""
	echo "Creation of the draft envelope has failed"
	echo ""
	cat $response
	exit 0
fi
echo ""
echo "Response:"
cat $response
echo ""
#Obtain the envelopeId from the API response.
ENVELOPE_ID=`cat $response | grep envelopeId | sed 's/.*\"envelopeId\":\"//' | sed 's/\",.*//'`

Step 5. Attach your bulk list ID to the envelope

Attach the listID obtained in step 3 to your envelope as a custom field named mailingListId. Make a request to the eSignature REST API using the generated envelope ID from step 4.

printf \
'{
	"listCustomFields": [],
	"textCustomFields": [{
		"name": "mailingListId",
		"required": false,
		"show": false,
		"value": "'"$BULK_LIST_ID"'"
	}]
}	
' >> $request_data
echo ""
echo "Adding the listId as an envelope custom field."
echo ""
response=$(mktemp /tmp/response-bs.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes/${ENVELOPE_ID}/custom_fields \
     "${Headers[@]}" \
     --data-binary @${request_data} \
     --output ${response})

Step 6. Initiate bulk send

Now that you have constructed an envelope and bulk list, make a request to the eSignature REST API and include the bulk list ID and envelope ID to initiate the bulk sending of envelopes to multiple recipients. Here’s how you make the call, but be sure to substitute your bulk list ID for {BULK_LIST_ID} and envelope ID for {ENVELOPE_ID}. Extract the batchId from the response into a variable for use in the next step:

printf \
'{
	"listId": "'"${BULK_LIST_ID}"'",
	"envelopeOrTemplateId": "'"${ENVELOPE_ID}"'",
}	
' >> $request_data
echo ""
echo "Initiating the Bulk Send."
echo ""
response=$(mktemp /tmp/response-bs.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request POST ${base_path}/v2.1/accounts/${account_id}/bulk_send_lists/${BULK_LIST_ID}/send \
     "${Headers[@]}" \
     --data-binary @${request_data} \
     --output ${response})
#If the Status code returned is greater than 201 (OK / Accepted), display an error message along with the API response. 
if [[ "$Status" -gt "201" ]] ; then
    echo ""
	echo "Initiating the Bulk Send has failed"
    echo ""
	cat $response
	exit 0
fi
echo ""
echo "Response:"
cat $response
echo ""
batchId=`cat $response | grep batchId | sed 's/.*\"batchId\":\"//' | sed 's/\",.*//'`

Step 7. Confirm successful batch send

Now that your bulk send operation has been initiated, check the progress of the operation by sending a request to the eSignature REST API, furnishing the batchId that was generated during the previous step. The sample code as configured here will wait for 10 seconds to give the API enough time to process the bulk envelopes from step 6.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

echo ""
echo "Confirming Bulk Send has initiated. -- ${batchId}"
echo ""
sleep 10s
response=$(mktemp /tmp/response-bs.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request GET ${base_path}/v2.1/accounts/${account_id}/bulk_send_batch/${batchId} \
     "${Headers[@]}" \
     --output ${response})

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

Sample response

{
  "batchId": "fefcbf2c-xxxx-xxxx-xxxx-681da196098b",
  "batchSize": "2",
  "sent": "0",
  "queued": "2",
  "failed": "0",
  "envelopeIdOrTemplateId": "caede1c7-xxxx-xxxx-xxxx-4657e05ae0db",
  "mailingListId": "3b464b42-xxxx-xxxx-xxxx-d8613e70030f",
  "ownerUserId": "c316f86c-xxxx-xxxx-xxxx-6b39358381d2",
  "senderUserId": "c316f86c-xxxx-xxxx-xxxx-6b39358381d2",
  "batchName": "sample.csv",
  "submittedDate": "2021-12-30T07:07:28.2900000Z",
  "envelopesUri": "/bulk_send_batch/fefcbf2c-xxxx-xxxx-xxxx-681da196098b/envelopes?start_position=0&count=40",
  "mailingListName": "sample.csv",
  "envelopesInfo": {
    "completed": "0",
    "declined": "0",
    "voided": "0"
  },
  "bulkErrors": []
}

Next steps

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.
Learn more about Bulk sending envelopes.
See how to Go-Live with a completed app and find the base path for API calls in the production environment.