Ask Anvil

The basic request

At minimum you send two things: the PDF template to sign, and the signers with the specific fields each one signs. Here is a complete example using Anvil's Etch e-sign API and its Node client:

const Anvil = require('@anvilco/anvil')

async function sendForSignature() {
  const anvilClient = new Anvil({ apiKey: process.env.ANVIL_API_KEY })

  const variables = {
    name: 'Loan Agreement',
    isDraft: false,
    isTest: true,
    files: [
      {
        id: 'loanAgreement',
        castEid: '05xXsZko33JIO6aq5Pnr', // a PDF template you built in Anvil
      },
    ],
    signers: [
      {
        id: 'borrower',
        name: 'Jane Doe',
        email: 'jane@example.com',
        signerType: 'email',
        fields: [
          { fileId: 'loanAgreement', fieldId: 'signature' },
        ],
      },
    ],
  }

  const response = await anvilClient.createEtchPacket({ variables })
  console.log(response.data?.data?.createEtchPacket)
}

sendForSignature()

That single call creates the packet and sends it. Each signer in the signers array gets an email with a secure link. The fields array maps a signer to the exact file and field they sign, so different people can sign different parts of the same document. Set signerType to embedded instead of email when you want to host the signing page inside your own app rather than send Anvil's email.

Controlling who signs first

Add a routingOrder value to each signer to control sequence. Signers that share the same routingOrder can sign in parallel, in any order among themselves. Signers with a higher number wait until everyone in the previous order has finished. Leave routingOrder out and signers are prompted in the order they appear in the array. A common pattern is two parties at routingOrder 1 and a countersigner at routingOrder 2.

Knowing when it is done

Do not poll for status. Register a webhook so the service notifies your app when a signer completes their part and when the full packet is executed. One billing detail worth knowing: Anvil's Etch API only counts a packet as billable once every signer has finished, at 1.50 dollars per completed packet, so sending a request that is never completed costs nothing.

Two things to watch. Keep your API key server-side, never in a browser, since it grants access to your whole organization. And make sure the fieldId values in your code match the field aliases defined on the PDF template, or signers will see signature boxes in the wrong place. Other e-signature APIs such as DocuSign and Dropbox Sign follow the same file-plus-signers shape, so the approach carries over even if the exact field names differ.