Embedding e-signatures into your app

PDF processes are core to every business, but the step involving filling and e-signing can be complex. Our e-signature API removes that layer of complexity, while giving you full control over the process. In this blog post, Ill be showing you how that works through an example.

The problem

You have a fully functioning React application, but youre missing one thing in your app flow: a way to fill PDFs and then gather e-signatures from your users. You want to provide your users with a consistent UX, where it feels like your application throughout the whole process.

Anvils Etch e-sign API provides two ways of notifying users to sign: the default solution with email, or the embedded solution through your app.

Today Ill be going over the embedded approach. The signer will not be sent an email when it is their turn to sign, instead, your app will direct the user to sign through an iframe or modal. Having your app redirect to the signing page then redirecting back to your app after signing is also an alternative.

To learn more about Etch signing with email notifications, check out our blog post on adding e-signatures to your app in 3 steps.

Goal

Our app is a portal for new hires to onboard into our company, and we require every new hire to sign two forms: an NDA and an IRS form W-4.

Our app flow will be as follows:

1. On the first page (/onboarding/start), the user will fill out a webform.
2. Our server will create a signature packet with the details submitted through the webform, then generate a link for embedded signing.
3. On the second page (/onboarding/sign/:signaturePacketEid), the user will sign the documents through an embedded signature frame.
4. The user will land on our third and last page (/onboarding/finish), which tells the user the onboarding process is complete.

Well be covering the following topics:

• Uploading a raw PDF and adding fields
• Using a PDF template
• Adding signers
• Pre-filling PDFs with data
• Requesting signatures for multiple PDFs
• Embedding the signing page into your React app

In this example well be using React, Node.js, Express.js, the node-anvil client to make requests to Anvil, and Anvil's SignatureFrame React component to embed the signing page into our app. If youre not using Node.js, rest assured because requests to Anvil from any platform will work the same.

Terminology

• Signature packet - a packet of PDF documents that require signatures
• PDF template (also known as a cast) - a templatized PDF that holds the configuration for where data and signatures will be filled into

Before we begin - Setup

1. Sign up for an Anvil account to retrieve your API key.
2. Proceed with authentication. Install the node-anvil client to your project.

yarn add @anvilco/anvil# ornpm install @anvilco/anvil

1. Import the Anvil client and create an instance in your server.

import Anvil from '@anvilco/anvil'// The API key is found under your organization settingsconst apiKey = '5AeDVVQ2ybDKqU8LktSVwFL63aLXgH2f'const anvilClient = new Anvil({ apiKey })

Building the first page new hire webform

First, lets build a simple web form for new hires to input their information, which will later be used to create a signature packet.

Client side:

  <form action="/api/packet/create" method="POST">    <input name="firstName" type="text" />    <input name="lastName" type="text" />    <input name="email" type="email" />    <input name="date" type="date" />    <input name="ssn" type="text" />    <input name="address" type="text" />    <input type="submit" value="Submit" />  </form>

Defining our signature packet

The NDA

This is the first out of two forms that the new hire will need to sign during the onboarding flow in our app. Since we dont have a PDF template pre-built for this file, well be uploading the PDF and specifying the fields for where data will be filled in the PDF.

Lets initialize this file as a JavaScript object first. Well use this later to create our signature packet.

const uploadedNDA = {  id: 'uploadedNDA',  title: 'Company Onboarding NDA',  file: anvilClient.prepareGraphQLFile('./static/onboardingNDA.pdf'),  fields: [    {      id: 'employeeSignature',      type: 'signature',      rect: { x: 270, y: 374, height: 22, width: 142 },      pageNum: 1,    },  ]}

The IRS Form W-4

After signing the NDA, the new hire should see this form next on the signing page. Good news, we already have a PDF template for this form on our Anvil dashboard. Using PDF templates is the simplest way to use Etch e-sign, since the fields configuration has already been defined.

Like the NDA, well initialize this PDF template as a JavaScript object. Well be using this later to create our signature packet.

const templateW4 = {  id: 'templateW4',  // castEid is also known as the 'PDF template ID'  // found under the 'API Info' tab on the PDF template page  castEid: 'nCpCqnkpRxjg1jNIUDZk',}

All files

This array holds all the files our new hire will be signing.

const packetFiles = [uploadedNDA, templateW4]

Add signers

The new hire is our only signer. We want the signer to be signing within our app, so well need signerType to be set to embedded. To ensure the new hire gets redirected to our confirmation page after signing, well need redirectURL to be set to /onboarding/finish.

const packetSigners = [  {    id: 'signer1',    // Important! This tells Anvil that our app will be    // notifying the signer when it is their turn to sign    signerType: 'embedded',    // Important! This tells Anvil to redirect to this URL    // after the signer has completed their signatures    redirectURL: '/onboarding/finish',    // fields left undefined to be filled using webform input    name: undefined,    email: undefined,    fields: [      {        fileId: 'uploadedNDA',        fieldId: 'employeeSignature',      },      {        fileId: 'templateW4',        fieldId: 'employeeSignature',      },    ],  }]

Prefill PDFs with data

const packetPrefillData = {  uploadedNDA: {    data: {      // fields left undefined to be filled using webform input      disclosingPartyName: undefined,      disclosingPartyEmail: undefined,      effectiveDate: undefined,      recipientName: 'Demo Company Inc.',      recipientEmail: '[email protected]',      purposeOfBusiness: 'DEMO!!',    },  },  templateW4: {    data: {      // fields left undefined to be filled using webform input      firstName: undefined,      lastName: undefined,      address: undefined,      ssn: undefined,    },  },}

Bringing our signature packet variables together

export const signaturePacketVariables = {  files: packetFiles,  signers: packetSigners,  data: {    payloads: {      ...packetPrefillData,    },  },}

Creating a route for our webform and generating a signature packet

When the new hire submits the webform on the first page, we need our server to use that information to create a signature packet using the node-anvil client.

Well achieve that by creating a route on our server which our first page webform will hit. This route retrieves the webform information from the request body, fills that data into the missing fields in our signature packet configuration defined in the previous section, and creates the signature packet. We can identify the signature packet created with the returned eid.

The user needs to land on the second page of our app flow after submitting the form, so well add a res.redirect() call to /onboarding/sign/:signaturePacketEid at the end of the route function.

Server side:

import {  signaturePacketVariables as variables} from '../variables'router.post('/api/packet/create', async (req, res) => {  // Extract the data submitted from the webform  const {     firstName, lastName, email, date, ssn, address,  } = req.body  // Fill in signer details  variables.signers[0].name = firstName + lastName  variables.signers[0].email = email  // Enter the prefill data for the NDA  variables.data.payloads.uploadedNDA.data = {    diclosingPartyName: firstName + lastName,    diclosingPartyEmail: email,    effectiveDate: date,  }  // Enter the prefill data for the W4  variables.data.payloads.templateW4.data = {    firstName,    lastName,    address,    ssn,  }  // Create the signature packet on the server  const {    statusCode, data, errors  } = await anvilClient.createEtchPacket({ variables })  // Pass the signature packet EID to the client-side  // for new hire to sign the packet  const signaturePacketEid = data.data.createEtchPacket.eid  const signingPageURL = `/onboarding/sign/${signaturePacketEid}`  return res.redirect(signingPageURL)})

After the new hire submits the webform on the first page, a signature packet is generated on the server, and the new hire lands on the second page. The documents are ready to be signed.

Retrieving our signature packet details and generating a signing URL

To embed a signing frame into the /onboarding/sign/:eid page of our app, a signing URL is required, which well generate using the node-anvil client.

Well do that upon rendering of the page.

this.state = { signURL: null }async componentDidMount () {  const response = await fetch('/api/packet/sign', {    method: 'POST',    headers: { 'Content-Type': 'application/json' },    body: JSON.stringify({      // clientUserId should be the signers ID in your system      clientUserId: 5,      signaturePacketEid: req.params.signaturePacketEid,    }),  })  const responseText = await response.text()  const { url } = JSON.parse(responseText)  this.setState({ signURL: url })}

Our server will fetch our signature packet details, and generate a signing URL for our new hire.

router.post('/api/packet/sign', async (req, res) => {  const { signaturePacketEid, clientUserId } = req.body  const { data } = await anvilClient.getEtchPacket({    variables: { eid: signaturePacketEid },  })  // We only have 1 signer for this signature packet  const signers = data.data.etchPacket.documentGroup.signers  const signerEid = signers[0].eid  // The signing URL generated here is used to  // embed the signing page into our app  const { url } = await anvilClient.generateEtchSignUrl({    variables: { signerEid, clientUserId }  })  return res.jsonp({ url })})

Note: Be sure to set clientUserId to the user ID in your system. This helps to provide user traceability from our system to yours. A key component is being able to show that an e-signature is associated with a given user, and that only that user has the capability to use their signature. Ensure that your app has measures in place to authenticate and authorize only this particular user to sign on their behalf.

Embedding the signature page

With the signing URL, we can proceed with embedding the signature page using the Anvil React component library.

We can choose between a frame or modal. For this example, well use the SignatureFrame component.

Install the component.

yarn add @anvilco/react-signature-frame# ornpm install @anvilco/react-signature-frame

Render the component onto our signing page.

import SignatureFrame from '@anvilco/react-signature-frame'class SigningPage extends React.Component {  state = { signURL: null }  async componentDidMount () {    const response = await fetch('/api/packet/sign', {      method: 'POST',      headers: { 'Content-Type': 'application/json' },      body: JSON.stringify({        // clientUserId should be the signers ID in your system        clientUserId: 5,        signaturePacketEid: req.params.signaturePacketEid,      }),    })    const responseText = await response.text()    const { url } = JSON.parse(responseText)    this.setState({ signURL: url })  }  render () {    return (      <>        <p>          Please review the documents and sign to complete           the onboarding process.        </p>        <SignatureFrame          signURL={this.state.signURL}          onFinish={            (redirectURL) => window.location.assign(redirectURL)          }        />      </>    )  }}

After signing, the onFinish function will be called, which in our case will route the user to redirectURL. We specified signer ones redirectURL to /onboarding/finish when creating our signature packet, so our signer will be routed to the onboarding completion page after signing.

Note: We used SignatureFrame for this example, but the process is the same for SignatureModal.

Summary

Weve gone through all the steps for integrating Anvils embedded signing process into your React app, from generating a signature packet using the Anvil Node-client to embedding the signing page using the Anvil React component library. I hope through this blog youve gained a better understanding of how the process works so you can incorporate this tool into your app!

Additional resources

• Try out our live example of Etch embedded signing
• Clone the example app repo to get a feel for using the E-signature API in your own Anvil account
• Take a look at our Etch E-sign API docs
• Anvil embedded signing React component library
• Handle requests and authentication with the Anvil Node-client
• Experiment with our API using the Anvil API Postman collection
• If youre interested in letting Anvil handle signing notifications through email, check out our blog on adding e-signature to your app in 3 steps

Questions or comments? Contact us at [email protected].