Create and send an envelope from a template

This tutorial walks you through creating and sending an envelope from a template via the API using the api-proxy. Templates allow you to pre-configure documents, recipients, and blocks in the UI, then create envelopes programmatically.

Prerequisites

• A Subnoto workspace with API credentials (access key and secret key)
• The API proxy container running (see API Proxy Usage)
• A programming language with HTTP client support (examples shown in Node.js)
• A template created in the Subnoto UI with documents, recipients (with labels), and blocks

Note: This tutorial presents examples in Node.js, but the Subnoto API can be used from any programming language. The API is language-agnostic and uses standard HTTP requests and JSON payloads. You can adapt these examples to Python, Go, Ruby, PHP, or any other language that supports HTTP requests.

Overview

When using templates, you configure the following in the Subnoto UI:

1. Template: Create a template with your document(s)
2. Recipients: Add recipients with labels (e.g., “customer”, “manager”, “signer”)
3. Blocks: Add signature blocks, text blocks, and image blocks assigned to recipient labels

Once the template is configured, you can create envelopes via the API by mapping recipient labels to actual recipients, then send the envelope.

Step 1: Create a Template in the UI

Before using the API, create your template in the Subnoto UI:

1. Log into your Subnoto workspace at app.subnoto.com
2. Navigate to Templates
3. Create a new template with your document
4. Add recipients with labels (e.g., “customer”, “manager”)
5. Add blocks (signature blocks, text blocks, image blocks) assigned to recipient labels

The template stores the document structure, recipient labels, and block positions. When you create an envelope from the template via the API, you’ll map these labels to actual recipients.

Step 2: Create Envelope from Template

Use the create-from-template endpoint to create an envelope from your template:

const API_BASE_URL = "http://localhost:8080";
const ACCESS_KEY = "your-access-key";
const SECRET_KEY = "your-secret-key";
const WORKSPACE_UUID = "your-workspace-uuid";

// Create envelope from template
const createResponse = await fetch(`${API_BASE_URL}/public/envelope/create-from-template`, {
    method: "POST",
    headers: {
        Authorization: `Bearer ${ACCESS_KEY}:${SECRET_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        workspaceUuid: WORKSPACE_UUID,
        templateUuid: "your-template-uuid",
        recipients: [
            {
                type: "manual",
                label: "customer",
                email: "[email protected]",
                firstname: "John",
                lastname: "Doe"
            },
            {
                type: "manual",
                label: "manager",
                email: "[email protected]",
                firstname: "Jane",
                lastname: "Smith"
            }
        ]
    })
});

const createResult = await createResponse.json();
const { envelopeUuid, documentUuids } = createResult;

Recipient Types

You can map template recipient labels to different recipient types:

Manual Recipient:

{
  type: 'manual',
  label: 'customer',
  email: '[email protected]',
  firstname: 'John',
  lastname: 'Doe'
}

Contact Recipient:

{
  type: 'contact',
  label: 'customer',
  contactUuid: 'contact-uuid'
}

Member Recipient:

{
  type: 'member',
  label: 'manager',
  userUuid: 'user-uuid'
}

Important Notes

• Label Matching: The label field in your recipients must match the recipient labels defined in your template. If a label doesn’t match, the request will fail with INVALID_RECIPIENT_LABELS.
• Template Structure: The template must include all documents, recipient labels, and blocks configured in the UI. The API creates the envelope by copying the template structure and mapping labels to actual recipients.

Step 3: Send the Envelope

After creating the envelope from the template, send it to all recipients:

const sendResponse = await fetch(`${API_BASE_URL}/public/envelope/send`, {
    method: "POST",
    headers: {
        Authorization: `Bearer ${ACCESS_KEY}:${SECRET_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        workspaceUuid: WORKSPACE_UUID,
        envelopeUuid,
        useUserAsSenderName: false, // Optional: use user name instead of company name
        customInvitationMessage: "Please review and sign this document" // Optional: custom message
    })
});

if (!sendResponse.ok) {
    throw new Error(`Failed to send envelope: ${sendResponse.status}`);
}

Important Notes

• Template Configuration: Templates, recipients, and blocks must be configured in the Subnoto UI before using the API. The API only creates envelopes from existing templates and maps recipient labels to actual recipients.
• Recipient Labels: The recipient label values in your API request must exactly match the recipient labels defined in your template. Template recipient labels are case-sensitive.
• Document Structure: The template’s document structure, including all blocks and their positions, is copied to the new envelope. You cannot modify blocks via the API when creating from a template.
• Envelope Status: After creating from a template, the envelope is in draft status. You must send it for recipients to receive signing invitations.

Error Handling

The API may return various error codes. Common ones include:

• WORKSPACE_NOT_FOUND: Invalid workspace UUID
• TEMPLATE_NOT_FOUND: Invalid template UUID or template doesn’t exist in the workspace
• INVALID_RECIPIENT_LABELS: One or more recipient labels don’t match the template’s recipient labels
• CONTACT_NOT_FOUND: Invalid contact UUID when using type: 'contact'
• USER_NOT_FOUND: Invalid user UUID when using type: 'member'

Always check response status codes and handle errors appropriately in your application.

Tracking Events with Webhooks

After sending an envelope, you can track signing events and completion using webhooks. See the Webhooks Setup Guide for details on setting up webhooks to monitor ENVELOPE_SIGNED and ENVELOPE_COMPLETED events.