DocuSign Momentum 2018DocuSign Momentum 2018
{"api":"esign_rest","category":"reference"}

BulkEnvelopes Resource

The BulkEnvelope resource provides methods that allow you to send the same document to a large number of recipients and get the status of the envelope.

General steps to use Bulk Send:

  • Create the bulk recipient CSV (Comma Separated Value) file that contains the list of recipient names and email addresses. The required and optional information that can be included the file is described in the [ML: BulkEnvelope: updateRecipients] method.
  • Create draft envelope by calling the Envelopes: createEnvelope method and add a bulk recipient signer. The envelope can be created from a template that has a bulk recipient. A bulk recipient signer is a Signer recipient type where isBulkRecipient property is set to true. There can only be one bulk recipient signer per envelope. Templates and draft envelopes can be saved with a bulk recipient signer, but a bulk recipient file must be uploaded before an envelope with a bulk recipient signer can be sent.
  • Add the bulk recipient file to the envelope by calling the BulkEnvelope: updateRecipients method.
  • Send the draft envelope by setting the status property on the envelope to sent and call the Envelopes:update method. Transitioning an envelope with a bulk recipient signer from created to sent triggers the sending of an envelope for each recipient in the associated bulk recipient file. The original (draft) envelope is discarded. The response returned from sending the envelope includes the following properties:
    • bulkRecipientsBatchId: Contains the batch identifier used to query the status of the entire bulk send operation.
    • bulkRecipientTransactions: Contains an array with identifying information about each envelope sent. The information included in this response:
      • transactionId: The ID used to reference the queued envelope transaction.
      • name: The name of the recipient assigned to this envelope transaction.
      • email: The email address of the recipient assigned to this envelope transaction.

Once you send an envelope with a bulk recipient file, DocuSign creates a separate envelope for each recipient in the bulk recipient file - eliminating the need to separately create and send an envelope for each signer. You can get the status of the bulk send by calling BulkEnvelopes: get or BulkEnvelopes: list methods.

You can customize authentication (access code, ID check, phone authentication, or social network IDs), add notes and other custom information for each recipient in the list by adding the information to the file.

Bulk Send Limitations:

  • Bulk send must be enabled for your account (accountSettings enableBulkRecipient is set to true) and for the user sending the envelopes (the allowBulkRecipients property in userSettings is set to true.)
  • Bulk send can only be used with Signer recipient types and there can only be one bulk recipient in an envelope or template. An envelope or template can have other Signers and recipient types that are added to the envelope or template normally. When a bulk recipient file is added to an envelope, the single bulk recipient Signer is replaced with all recipients in the bulk recipient file. There can only be one bulk recipient file associated with an envelope when it is sent.
  • When an envelope with bulk recipients is sent, the envelopes are added to a bulk recipient queue and sent in a metered fashion. There is a limit of 2,000 envelopes in the bulk recipient queue and an error message is shown to the sender if this limit is reached. If you receive this error, you should wait and resend the envelope at a later time.

If you frequently run into queue limits, you can contact your account manage to discuss modifying the queue limits for your account.

MethodDescription
list
GET /v2/accounts/{accountId}/bulk_envelopes

Retrieves status information about all the bulk recipient batches. A bulk recipient batch is the set of envelopes sent from a single bulk recipient file. The response includes general information about each bulk recipient batch.

The response returns information about the envelopes sent with bulk recipient batches, including the batchId property, which can be used to retrieve a more detailed status of individual bulk recipient batches.

get
GET /v2/accounts/{accountId}/bulk_envelopes/{batchId}

Retrieves the status information of a single bulk recipient batch. A bulk recipient batch is the set of envelopes sent from a single bulk recipient file.