How to Bulk Up (Your eSignature Requests!)

If you're using the GraphQL API and you've seen the new Bulk Send Tool - you might think you'd really like to use that in your automation. You're in luck! Everything done in the bulk tool is handled through the GraphQL API and you can adapt it any way you want.

Let's have a quick look at what we mean by a Bulk Send on the Legalesign platform. If you haven't run through the basic GraphQL tutorials now is the time to switch back and look them over.

What is a Bulk Send?

We assume that you're sending more than a handful (although small numbers work) of signing requests for a specific template. Remember that the account you authorize your code with must have access to that template and have enough credit to send your requests. In the early stages of testing this code you may want to skip the actual start, add and send mutations to avoid being charged for those requests - if this is a problem get in touch with our support for help.

A bulk send groups all your document requests together, that way you can have a unique view of the progress of each bulk job. Imagine there's a large mail-out that happens monthly, you'll probably call each bulk job something like 'May Campaign' and be able to see how many were completed, bounced or rejected in Console. Console also retrieves your list incrementally so that you can potentially view more than the usual maximum item limit (1000).

Given the jobs potentially large number of documents and recipients, the system spreads these out over time so that you don't hit you organisations maximum request limit. This is the reason why the Bulk Details page periodically refreshs for you. A bulk job can take around 5-6 seconds to be accepted and started by the system and then documents will be processed approximately one per second.

How do I do that with code instead?

You may not have a CSV file but you could have an internal database, queue or file system - and you want to iterate through that list, making a document request for each, and then send the result as a bulk. Could be pretty daunting but we've got you covered.

Start Bulk

Once you've got a list ready of all the recipients that you want to use with your template (it's a good idea to look at the example CSV produced by the Bulk Tool) you'll want to tell the platform you're ready to start a bulk transaction. Here's what that call will look like:

    mutation startBulk {
      startBulk(input : { groupId: "${groupId}", name: "${name}"})
    }

This will return a bulk ID that you'll need to keep to hand for every other mutation call that you'll need in this process.

Add a Bulk Document

Now you can iterate through each Document you have in your list adding one or more Recipients. Some of the fields given here are optional - for full details consult the GraphIQL Explorer. Remember the bulkId is the ID that you recieved when you started the job.

You'll need to provide a sendOrder index each document in your list - this doesn't ensure the order in which things are recieved (unlike some other types of send) but it tells the system how to queue your items.

  mutation addBulkDocument{
      addBulkDocument(input: {
          bulkId: "bulkId", 
          sendOrder: 0,
          document: {
            groupId: "", 
            allowCopying: false, 
            allowPrinting: false, 
            templateId: "", 
            title: "", 
            sequentialSigning: false, 
            suppressEmails: false, 
            senderFields: [],
            participantFields: [],
            tag: "order",
            pdfPassword: "",
            retainPdfPassword: false,
            recipients: []
          }
        }
      )
    }

Send Bulk Job

Now you're ready to commit the work to the platform. Here's all you need to kick the job off:

    mutation sendBulk {
      sendBulk(input : { 
        groupId: "<groupId>",
        name: "Bulk Send Trial Name",
	      bulkId: "${bulkId}",
        enforceOrder: false,
        notifySender: false,
        notifySenderAttach: false,
        notifyParticipants: false,
        notifyParticipantsAttach: false
      })
    }

And that is how it's done!