Skip to main content

Getting to Send

· 4 min read
Alex Weinle
Alex Weinle
GraphQL Developer and AWS Architect

There's a lot of documentation around the Legalesign platform - but if you're like me then you'll want to send an example document as quickly as possible - because that's what makes the magic happen. In this article we'll walk through how to use the new Document Viewer component in compose mode to create a seamless document preparation and sending experience for your users.

What's a mutation​

In GraphQL, a mutation is a type of operation that allows you to modify data on the server. Unlike queries, which are used to fetch data, mutations are used to create, update, or delete data. When you perform a mutation, you typically specify the fields you want to modify and the new values for those fields.

The Send Mutation​

The send mutation is a specific GraphQL mutation provided by the Legalesign API that allows you to send a document for signing, witnessing or approval. This mutation typically requires you to provide the document ID, the recipients' information, and any additional settings or options for the sending process.

Let's look at one:

mutation sendSingleDocument {
  send(
    input: {
      title: "Your Template"
      templateId: "dHBsYTZkZTA1ZDMtMTE4YS0xMWYxvWE1M2MtMDY5NzZlZmU0MzIx"
      groupId: "Z3JwZGVtVGbzE="
      tag: ""
      pdfPassword: ""
      retainPdfPassword: true
      allowPrinting: false
      allowCopying: false
      sequentialSigning: true
      documentCCEmail: []
      senderFields: []
      participantFields: []
      recipients: [
        {
          id: "cm9sYTZkZTI5YzItMTE4YS0xMWYxLWE1M2MtMDY5NzZlZmU0MzIx"
          order: 0
          signerIndex: 1
          role: ""
          roleId: "cm9sYTZkZTI5YzItMTE4YS0xMWYxLWE1M2MtMDY5NzZlZmU0MzIx"
          experience: "ZXhwZGVtbzE="
          firstName: "Alex"
          phoneNumber: ""
          attachments: []
          lastName: "Weinle"
          email: "alex@legalesign.test"
          scheduleId: "c2NoNzE0"
          expiryDate: null
          timeZone: "Europe/London"
          skipped: false
        }
      ]
    }
  )
}

Let's focus on the critical parts here that you'll need to alter and execute your own version of this mutation.

The easiest way to get a graphql mutation

that matches your group and template is to perform a test send in console.legalesign.com and watch the network panel in your browser. You'll be able to see a graphql request in the payload.

alt text

IDs and Where To Get Them​

On the Legalesign system a group has templates which are reusable documents that know a lot about the fields (including a signature box) and roles of each recipient you want to send the document with a particular experience. For more details see the What's What on Legalesign.

You could call for these via the GraphQL API, but in this article we're all about speed and experiementing, so feel free to grab the IDs directly from the Console URLs in the browser when you're looking at a group or template.

Where to Test A Mutation​

We provide you with the GraphIQL Tool (notice that extra I?) to execute queries on the fly. First login into Console and then navigate to Legalesign GraphIQL Tool. Paste in your send mutation and your ready to go.

warning

Be careful when executing mutations in GraphIQL as they will have real effects. Always double-check your mutation and consider using a test email account. Stay safe.

Run your mutation in the GraphIQL tool and check you get a successful ID returned. If all is good with the send request, check your test email inbox for a signing request (requests are normally fulfilled in 5-10 seconds).

Going Further​

Ok, so now you can execute your own send mutation, you probably want to put it to use in your own system. In our test we used the GraphIQL tool and our login to set up an authorized connection. To embed this into you code you'll need a valid Legalesign account username and password (it's usually best to set up a dedicated user, and maybe an automation group for it to send from).

Check out the following resources that explain how to authorize a library to send a mutation:

Introduction to the GraphQL API

GraphQL API Libraries

GitHub Node Example Repository

GitHub C# Example Repository