Upload Files to the Platform

Many tasks require you to provide a file for the Legalesign platform to use, such as a file to use as a template or an image to use for a signature.

The platform requires you to place this file in the correct sub-folder of our clearing system. This will vet your file for possible security issues and pass it on to the correct location for its purpose.

What You'll Learn

This guide will walk you through uploading files to Legalesign. Don't worry if you're new to APIs or cloud storage - we'll explain each step clearly.

What is a Pre-Signed URL?

A pre-signed URL is like a temporary access pass. Instead of giving you permanent access to our storage, we give you a special URL that:

• Only works for a short time (15 minutes)
• Only allows you to upload one specific file
• Keeps your files secure

Think of it like a valet parking ticket - it gives temporary, limited access for a specific purpose.

What is S3?

S3 (Simple Storage Service) is Amazon's cloud file storage. It's where we safely store your documents, logos, and other files. You don't need to understand S3 in detail - just know that it's a secure place to store files in the cloud.

Overview

The upload process follows these steps:

1. Request a pre-signed upload URL from the GraphQL API (ask for permission to upload)
2. Upload your file to S3 using the provided URL (actually send the file)
3. The platform automatically processes and validates the file (we check it's safe)
4. The file is moved to its final destination (we put it in the right place)

Why This Two-Step Process?

You might wonder why we don't just let you upload directly. This two-step process:

• Ensures you have permission to upload
• Prevents unauthorized file uploads
• Allows us to scan files for viruses
• Keeps track of who uploaded what

Step 1: Request Upload URL

Use the upload query to obtain a pre-signed URL for your file upload (in this case a PDF). See our authentication guide for more information on how to get started running GraphQL queries. For full argument details, see the upload query reference.

query {
  upload(
    id: "<BASE64_OBJECT_ID>",
    uploadType: TEMPLATE,
    extension: "pdf"
  ) {
    url
  }
}

Parameters Explained

• id: Base64-encoded object ID (e.g., template ID, experience ID)
• uploadType: The type of file being uploaded (see below)
• extension: File extension (pdf, png, jpg)

Upload Types

• TEMPLATE - PDF files for document templates
• LOGO - Images for signing page branding
• EMAILLOGO - Images for email branding
• ATTACHMENT - Additional files to attach to documents

See UploadType enum for the full list.

Step 2: Upload to S3

The query returns a pre-signed URL. Send your file to this URL using an HTTP PUT request:

const response = await fetch(url, {
  method: 'PUT',
  body: fileData,
  headers: {
    'Content-Type': 'application/pdf' // or appropriate MIME type
  }
});

Step 3: Automatic Processing

Once uploaded, the platform:

1. Scans the file for viruses and security threats
2. Validates the file format and content
3. Processes the file (e.g., extracts page dimensions for PDFs)
4. Moves it to the final storage location with appropriate permissions

Complete Example

JavaScript

import { generateClient } from 'aws-amplify/api';

const uploadFile = async (objectId, file) => {
  const client = generateClient();
  const extension = file.name.split('.').pop();
  
  // Step 1: Get upload URL
  const result = await client.graphql({
    query: `
      query {
        upload(
          id: "${objectId}",
          uploadType: TEMPLATE,
          extension: "${extension}"
        ) {
          url
        }
      }
    `
  });
  
  const uploadUrl = result.data.upload.url;
  
  // Step 2: Upload file
  const response = await fetch(uploadUrl, {
    method: 'PUT',
    body: file,
    headers: {
      'Content-Type': file.type
    }
  });
  
  if (!response.ok) {
    throw new Error('Upload failed');
  }
  
  return { success: true };
};

Python

import requests
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

def upload_file(graphql_endpoint, auth_token, object_id, file_path):
    extension = file_path.split('.')[-1]
    
    transport = RequestsHTTPTransport(
        url=graphql_endpoint,
        headers={'Authorization': auth_token}
    )
    client = Client(transport=transport, fetch_schema_from_transport=True)
    
    query = gql(f'''
        query {{
            upload(
                id: "{object_id}",
                uploadType: TEMPLATE,
                extension: "{extension}"
            ) {{
                url
            }}
        }}
    ''')
    
    result = client.execute(query)
    upload_url = result['upload']['url']
    
    with open(file_path, 'rb') as f:
        file_data = f.read()
    
    response = requests.put(
        upload_url,
        data=file_data,
        headers={'Content-Type': 'application/pdf'}
    )
    
    if response.status_code != 200:
        raise Exception('Upload failed')
    
    return {'success': True}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using GraphQL;
using GraphQL.Client.Http;
using GraphQL.Client.Serializer.Newtonsoft;

public class FileUploader
{
    public async Task<bool> UploadFile(string graphqlEndpoint, string authToken, 
                                       string objectId, string filePath)
    {
        var extension = Path.GetExtension(filePath).TrimStart('.');
        
        var graphQLClient = new GraphQLHttpClient(
            graphqlEndpoint, 
            new NewtonsoftJsonSerializer()
        );
        graphQLClient.HttpClient.DefaultRequestHeaders.Add("Authorization", authToken);
        
        var query = new GraphQLRequest
        {
            Query = $@"
                query {{
                    upload(
                        id: ""{objectId}"",
                        uploadType: TEMPLATE,
                        extension: ""{extension}""
                    ) {{
                        url
                    }}
                }}
            "
        };
        
        var response = await graphQLClient.SendQueryAsync<dynamic>(query);
        string uploadUrl = response.Data.upload.url;
        
        using var httpClient = new HttpClient();
        var fileBytes = await File.ReadAllBytesAsync(filePath);
        var content = new ByteArrayContent(fileBytes);
        content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
        
        var uploadResponse = await httpClient.PutAsync(uploadUrl, content);
        
        if (!uploadResponse.IsSuccessStatusCode)
        {
            throw new Exception("Upload failed");
        }
        
        return true;
    }
}

Path Format

Files follow this naming convention:

<uploadType>/<userId>/<base64ObjectId>.<extension>

Example:

template/usr123abc/dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx.pdf

note

You don't need to create this path yourself - the API handles it automatically when you provide the correct parameters.

Supported File Types

Templates

• PDF files only
• Maximum size: 50MB

Logos and Email Logos

• PNG, JPG, JPEG
• Maximum size: 5MB
• Recommended dimensions: 200x200px (logos), 600x200px (email logos)

Attachments

• PDF, DOC, DOCX, XLS, XLSX, PNG, JPG
• Maximum size: 25MB

Error Handling

• No permission: The object ID doesn't belong to your account or group
• Invalid extension: File type not supported for this upload type
• File too large: Exceeds maximum size limit
• Virus detected: File failed security scan

Security Notes

• Pre-signed URLs expire after 15 minutes
• Files are scanned for viruses before processing
• Only users with appropriate permissions can upload files
• Files are isolated during processing in the clearing bucket

Best Practices

1. Always check file size before uploading
2. Use the correct file format
3. Handle errors gracefully
4. Don't reuse pre-signed URLs
5. Keep your credentials secure — never share authentication tokens or embed them in client-side code