Skip to main content

Upload a File as a Template

This guide walks you through the complete process of creating a template and uploading a PDF, image, or Word file to use as your document template in Legalesign.

tip

Need real-time feedback on upload processing? See Track Upload Progress with Subscriptions.

What You'll Learn​

By the end of this guide, you'll know how to:

  1. Create a new template in your Legalesign group
  2. Get the template ID and upload URL from the mutation response
  3. Upload your source file to the template
  4. Verify the upload was successful

Prerequisites​

Before you start, make sure you have:

  • A Legalesign account with API access
  • Your authentication credentials (see our authentication guide)
  • A PDF, image, or Word file ready to upload (maximum 50MB)
  • Your group ID (the workspace where you want to create the template)

The Complete Process​

Step 1: Create a Template​

First, create an empty template in Legalesign. This returns both the template ID and a pre-signed upload URL for the PDF upload. To do this you'll need to run a GraphQL mutation, if you haven't done this before see the Introduction to GraphQL.

What is a Template?​

A template is a reusable document structure in Legalesign. Once you upload a PDF to a template, you can:

  • Add signature fields and form fields
  • Send it to multiple recipients
  • Reuse it for different signers

GraphQL Mutation​

mutation CreateTemplate($input: templateCreateInput!) {
  createTemplate(input: $input) {
    id
    uploadUrl
  }
}

Input Variables​

{
  "input": {
    "groupId": "grpYourGroupAPIId",
    "title": "Employment Contract Template"
  }
}

Parameters Explained​

  • groupId: The base 64 ID of your group/workspace (you can grab this from the URL in Console https://console.legalesign.com/)
  • title: A descriptive name for your template (you can change this later)

Step 2: Extract the Template ID and Upload URL​

The mutation returns a templateCreateOutput object. Save the id field and the uploadUrl string.

Example response:

{
  "data": {
    "createTemplate": {
      "id": "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx",
      "uploadUrl": "https://s3.amazonaws.com/bucket/path?signature=..."
    }
  }
}
tip

The template ID is a Base64-encoded string. Save both values from the response. The uploadUrl is short-lived and should be used promptly.

Step 3: Upload Your PDF​

Use the returned uploadUrl to upload your PDF file directly to S3. This will be different depending on your development stack. In our javascript example we've used fetch but you can use other libraries including aws-amplify.

Complete Working Examples​

import fs from 'fs';

const AUTH_TOKEN = '<token-from-authentication-guide>';

const uploadPdfTemplate = async (groupId, title, pdfFilePath) => {
  const graphqlEndpoint = 'https://graphql.uk.legalesign.com/graphql';
  
  // Step 1: Create the template
  console.log('Creating template...');
  const createResponse = await fetch(graphqlEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${AUTH_TOKEN}`
    },
    body: JSON.stringify({
      query: `
        mutation CreateTemplate($input: templateCreateInput!) {
          createTemplate(input: $input) {
            id
            uploadUrl
          }
        }
      `,
      variables: {
        input: {
          groupId: groupId,
          title: title
        }
      }
    })
  });
  
  const createResult = await createResponse.json();
  const templateId = createResult.data.createTemplate.id;
  const uploadUrl = createResult.data.createTemplate.uploadUrl;
  console.log('Template created with ID:', templateId);
  
  // Step 2: Upload the PDF
  console.log('Uploading PDF...');
  const fileData = fs.readFileSync(pdfFilePath);
  
  const uploadResponse = await fetch(uploadUrl, {
    method: 'PUT',
    body: fileData,
    headers: {
      'Content-Type': 'application/pdf'
    }
  });
  
  if (!uploadResponse.ok) {
    throw new Error(`Upload failed: ${uploadResponse.statusText}`);
  }
  
  console.log('PDF uploaded successfully!');
  
  return {
    success: true,
    templateId: templateId,
    title: title
  };
};

// Usage example
uploadPdfTemplate(
  'grpYourGroupId',
  'Employment Contract',
  './contract.pdf'
).then(result => {
  console.log('Complete!', result);
}).catch(error => {
  console.error('Error:', error);
});

No additional dependencies needed — Node.js 18+ includes fetch natively.

What Happens After Upload?​

Once your PDF is uploaded, Legalesign automatically:

  1. Scans for viruses - Ensures the file is safe
  2. Validates or converts the file - Checks PDFs are valid, or converts supported files such as Word documents and images into PDF
  3. Extracts page information - Gets page count and dimensions
  4. Processes the file - Optimizes it for viewing and signing
  5. Stores it securely - Moves it to permanent storage

This process usually takes a few seconds. Once complete, your template is ready to use!

Adding Signatures and Fields​

If you want to automate participants and field placement, you can prepare the source file before upload in a couple of different ways:

  • Text tags - Add Legalesign text tags into the source document so participants, signature fields, and form fields can be created automatically during processing. See the REST API explanation in the quickstart tutorial and the Convert text tags endpoint reference.
  • Embedded PDF fields - If your PDF already contains embedded form fields, Legalesign can use those as part of the upload and template preparation workflow.

Next Steps​

Now that you have a template with a PDF, you can:

  1. Add signature fields - Use the createTemplateElement mutation to add fields
  2. Create roles - Define who will sign the document
  3. Send for signing - Use the send mutation to send to recipients

Common Issues and Solutions​

"No permission" Error​

Verify your group ID is correct and you're authenticated with the right account.

"File too large" Error​

Compress your PDF — the maximum is 50MB.

Upload URL Expired​

Use the uploadUrl returned by createTemplate promptly. If it expires before you upload, request a fresh URL with the upload query using the saved template ID.

"Invalid PDF" Error​

Open the PDF in a PDF reader to verify it's valid, then re-export or re-save it.

Track Upload Progress​

To get real-time feedback on upload processing (scanning, validation, completion), use subscriptions. See Track Upload Progress with Subscriptions.

Export This Article

Save a copy of this page as PDF or plain text.