Using Dropbox Sign’s API to Bulk Send with Templates (+ Code Example)

What if you could maximize the impact of an action without having to do more work? You can do exactly that with Dropbox Sign's newest API feature: Bulk Send with Template. This new feature allows you to send up to 250 separate signature requests using a template with a single API request. As a reminder, templates are a great way to customize a file for signature requests that need to be sent out repeatedly to multiple recipients.

‍

When using the Bulk Send with Template endpoint, you’re able to send the signature request to a list of signers via the signer_list or the signer_file parameters. The signer_list parameter accepts a JSON array that defines the values and options of signers. This parameter is required unless a signer_file is used, you may not use both.

‍

The signer_file parameter is super handy when sending signature requests to a large list of signers provided within an uploaded CSV file. Examples of this might be petition lists, volunteer sign-up lists, school permission slips, community events, etc.

‍

Let’s walk through how it works.

‍

In this simple example, we will use the signer_list parameter for a request with 3 signers.

‍

Before we get started, you need to create a template to send out for signature. Follow this simple guide on How to Create a Template and be sure to save the template_id.

‍

Now that you have your template_id handy, we will be making the call to the API using the /v3/signature_request/bulk_send_with_template endpoint. In addition to your template_id, you will need to grab your API Key from your account settings.

‍

In this example, we will be using cURL and request-promise, a Node.js request library. In the future, you can use one of the six Dropbox Sign SDKs to make this request.

‍

cURL Example:

‍

CODE: https://gist.github.com/latoyazamill/8e616a3e9d6ad79ea197e8def3a01be3.js

‍

Node.js Example:

‍

CODE: https://gist.github.com/latoyazamill/b4b2f77aa3068ba38fb14612f6f484af.js

‍

Response:

‍

CODE: https://gist.github.com/latoyazamill/6f062cb50f565b854bdd22ffb80ca9dc.js

‍

Description:

‍

• bulk_send_job_id: This is a unique identifier that is associated with all of the Signature Requests created for this Bulk Send Job.
• total: The number of Signature Requests generated from this Bulk Send Job
• is_creator: This is always true for the creator. This is set to false when searching as a team admin with the Get Bulk Send Job or List Bulk Send Jobs endpoints.
• created_at: Unix timestamp for when the Bulk Send Job was created.

‍

Once your Bulk Send Job has been properly sent you will receive an automated message from Dropbox Sign that includes the Bulk Send Job ID.

‍

‍

You can you use the following endpoint to check the status of the Bulk Send Job:

‍

Get Bulk Send Job
GET /bulk_send_job/[:bulk_send_job_id]
Returns a BulkSendJob that includes all SignatureRequests sent.

‍

Since you are sending a non-embedded signature request, your users receive email notifications from Dropbox Sign and will sign the documents online.

‍

Congrats! You’ve just completed your first Bulk Send Job. As promised, here is an example of the cURL Request using a CSV file.

‍

cURL Request:

‍

CODE: https://gist.github.com/latoyazamill/46f8a550d7a4f182ad8dfb282b5c7be1.js

‍

Example CSV File Format:

‍

Note: Any column with a "_field" suffix will be treated as a custom field (optional). You may only specify field values here, any other options should be set in the custom_fields request parameter. You can learn more about using custom_fields in our API Documentation.

‍

Happy Bulk Sending!

‍