Skip to main content

Upload a PDF Template

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

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 needed for upload
  3. Upload your PDF 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 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 gives you a template ID that you'll use 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) {
    template {
      id
      title
      groupId
      created
    }
  }
}

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​

The mutation returns a template object. Save the id field — this is what you'll use to upload your PDF.

Example response:

{
  "data": {
    "createTemplate": {
      "template": {
        "title": "Employment Contract Template",
        "groupId": "grpYourGroupId"
      }
    }
  }
}
tip

The template ID is a Base64-encoded string. Save this ID - you'll need it for the next step.

Step 3: Request Upload Permission​

Now that you have a template ID, request a pre-signed URL to upload your PDF.

query GetUploadUrl {
  upload(
    id: "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx",
    uploadType: TEMPLATE,
    extension: "pdf"
  ) {
    url
  }
}

Parameters​

  • id: The template ID from Step 2
  • uploadType: Must be TEMPLATE for PDF templates
  • extension: Must be "pdf" for template files

The response will contain a pre-signed URL:

{
  "data": {
    "upload": {
      "url": "https://s3.amazonaws.com/bucket/path?signature=..."
    }
  }
}
note

This URL is only valid for 15 minutes. If it expires, simply request a new one.

Step 4: Upload Your PDF​

Use the pre-signed URL 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 LEGALESIGN_AUTH_ENDPOINT = 'https://cognito-idp.eu-west-2.amazonaws.com';
const CLIENT_ID = '<your-client-id>';
const USERNAME = '<your-username>';
const PASSWORD = '<your-password>';

const getToken = async () => {
  const response = await fetch(LEGALESIGN_AUTH_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-amz-json-1.1',
      'X-Amz-Target': 'AWSCognitoIdentityProviderService.InitiateAuth'
    },
    body: JSON.stringify({
      AuthFlow: 'USER_PASSWORD_AUTH',
      ClientId: CLIENT_ID,
      AuthParameters: { USERNAME, PASSWORD }
    })
  });
  const data = await response.json();
  if (data.__type) throw new Error(`Auth failed: ${data.message}`);
  return data.AuthenticationResult.AccessToken;
};

const uploadPdfTemplate = async (groupId, title, pdfFilePath) => {
  const graphqlEndpoint = 'https://graphql.uk.legalesign.com/graphql';
  
  console.log('Authenticating...');
  const authToken = await getToken();
  
  // Step 1: Create the template
  console.log('Creating template...');
  const createResponse = await fetch(graphqlEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${authToken}`
    },
    body: JSON.stringify({
      query: `
        mutation CreateTemplate($input: templateCreateInput!) {
          createTemplate(input: $input) {
            template {
              id
              title
            }
          }
        }
      `,
      variables: {
        input: {
          groupId: groupId,
          title: title
        }
      }
    })
  });
  
  const createResult = await createResponse.json();
  const templateId = createResult.data.createTemplate.template.id;
  console.log('Template created with ID:', templateId);
  
  // Step 2: Get upload URL
  console.log('Requesting upload URL...');
  const uploadUrlResponse = await fetch(graphqlEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${authToken}`
    },
    body: JSON.stringify({
      query: `
        query GetUploadUrl($id: ID!) {
          upload(
            id: $id,
            uploadType: TEMPLATE,
            extension: "pdf"
          ) {
            url
          }
        }
      `,
      variables: {
        id: templateId
      }
    })
  });
  
  const uploadUrlResult = await uploadUrlResponse.json();
  const uploadUrl = uploadUrlResult.data.upload.url;
  console.log('Upload URL received');
  
  // Step 3: 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 the PDF - Checks it's a valid PDF format
  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!

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​

Request a new upload URL by running the upload query again. URLs expire after 15 minutes.

"Invalid PDF" Error​

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

Export This Article

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