Templates API

POST /envelope/use
Content-Type: multipart/form-data

{
  "id": "envelope_document123",
  "recipients": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "token": "recipient_token",
      "role": "SIGNER",
      "signingOrder": 1,
      "signingUrl": "https://app.documenso.com/sign/recipient_token"
    }
  ]
}

const distributionResponse = await fetch(
  'https://app.documenso.com/api/v2/envelope/distribute',
  {
    method: 'POST',
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      envelopeId: document.id,
    }),
  },
);

const distribution = await distributionResponse.json();
console.log('Signing URL:', distribution.recipients[0].signingUrl);

{
  "success": true,
  "id": "envelope_document123",
  "recipients": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "token": "recipient_token",
      "role": "SIGNER",
      "signingOrder": 1,
      "signingUrl": "https://app.documenso.com/sign/recipient_token"
    }
  ]
}

{
  "id": 123,
  "envelopeId": "envelope_abc123xyz",
  "type": "PRIVATE",
  "visibility": "EVERYONE",
  "title": "Employment Contract",
  "externalId": "template-emp-001",
  "publicTitle": null,
  "publicDescription": null,
  "userId": 1,
  "teamId": 5,
  "folderId": null,
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-10T08:30:00.000Z",
  "recipients": [
    {
      "id": 1,
      "email": "employee@example.com",
      "name": "Employee",
      "role": "SIGNER",
      "signingOrder": 1
    },
    {
      "id": 2,
      "email": "hr@company.com",
      "name": "HR Manager",
      "role": "SIGNER",
      "signingOrder": 2
    }
  ],
  "fields": [
    {
      "id": 101,
      "type": "SIGNATURE",
      "page": 1,
      "positionX": 10,
      "positionY": 80,
      "width": 30,
      "height": 5,
      "recipientId": 1
    }
  ],
  "templateMeta": {
    "subject": "Your Employment Contract",
    "message": "Please review and sign your employment contract.",
    "redirectUrl": "https://example.com/welcome"
  },
  "directLink": null
}

GET /template

{
  "data": [
    {
      "id": 123,
      "envelopeId": "envelope_abc123",
      "type": "PRIVATE",
      "title": "Employment Contract",
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-01-10T08:30:00.000Z",
      "recipients": [
        {
          "id": 1,
          "email": "employee@example.com",
          "name": "Employee",
          "role": "SIGNER"
        }
      ]
    }
  ],
  "count": 25,
  "currentPage": 1,
  "perPage": 10,
  "totalPages": 3
}

GET /template/{templateId}

POST /template/use

{
  "id": 789,
  "envelopeId": "envelope_xyz789",
  "status": "PENDING",
  "source": "TEMPLATE",
  "title": "Employment Contract",
  "externalId": "contract-2025-001",
  "recipients": [
    {
      "id": 1,
      "envelopeId": "envelope_xyz789",
      "documentId": 789,
      "templateId": null,
      "email": "john.doe@example.com",
      "name": "John Doe",
      "role": "SIGNER",
      "signingStatus": "NOT_SIGNED",
      "signingOrder": 1
    }
  ]
}

const document = await response.json();

const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
  method: 'POST',
  headers: {
    Authorization: API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    envelopeId: document.envelopeId,
  }),
});

const distribution = await distributionResponse.json();
console.log('Signing URL:', distribution.recipients[0].signingUrl);

const response = await fetch(`${BASE_URL}/template/use`, {
  method: 'POST',
  headers: {
    Authorization: API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 123,
    recipients: [{ id: 1, email: 'signer@example.com', name: 'Signer' }],
    override: {
      title: 'Custom Document Title',
      subject: 'Custom email subject',
      message: 'Custom email message body',
      timezone: 'America/New_York',
      dateFormat: 'MM/dd/yyyy',
      redirectUrl: 'https://example.com/custom-redirect',
      language: 'de',
      typedSignatureEnabled: true,
      uploadSignatureEnabled: false,
      drawSignatureEnabled: true,
    },
    distributeDocument: true,
  }),
});

type PrefillField = {
  id: number; // Field ID from template
  type: string; // Field type (must match template field)
  label?: string; // Optional label override
  placeholder?: string; // Optional placeholder (text/number only)
  value: string | string[]; // Value to prefill
};

const response = await fetch(`${BASE_URL}/template/use`, {
  method: 'POST',
  headers: {
    Authorization: API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 123,
    recipients: [{ id: 1, email: 'signer@example.com', name: 'Signer' }],
    prefillFields: [
      // Text field
      {
        id: 101,
        type: 'text',
        value: 'John Doe',
      },
      // Number field
      {
        id: 102,
        type: 'number',
        value: '50000',
      },
      // Date field
      {
        id: 103,
        type: 'date',
        value: '2025-03-15',
      },
      // Radio field (select one option)
      {
        id: 104,
        type: 'radio',
        value: 'full-time',
      },
      // Checkbox field (select multiple options)
      {
        id: 105,
        type: 'checkbox',
        value: ['health', 'dental', '401k'],
      },
      // Dropdown field
      {
        id: 106,
        type: 'dropdown',
        value: 'engineering',
      },
    ],
    distributeDocument: true,
  }),
});

POST /template/update

POST /template/duplicate

POST /template/delete

{
  "success": true
}

POST /template/direct/create

{
  "id": 456,
  "token": "abc123xyz",
  "templateId": 123,
  "directTemplateRecipientId": 1,
  "enabled": true,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

POST /template/direct/toggle

POST /template/direct/delete

const API_TOKEN = process.env.DOCUMENSO_API_TOKEN;
const BASE_URL = 'https://app.documenso.com/api/v2';

async function sendEmploymentContract(employeeData: {
  email: string;
  name: string;
  position: string;
  salary: number;
  startDate: string;
}) {
  // 1. Get the template to find recipient and field IDs
  const templateResponse = await fetch(`${BASE_URL}/template/456`, {
    headers: { Authorization: API_TOKEN },
  });
  const template = await templateResponse.json();

  // 2. Find the employee recipient slot
  const employeeRecipient = template.recipients.find(
    (r) => r.role === 'SIGNER' && r.signingOrder === 1
  );

  // 3. Find fields to prefill
  const positionField = template.fields.find(
    (f) => f.fieldMeta?.label === 'Position'
  );
  const salaryField = template.fields.find(
    (f) => f.fieldMeta?.label === 'Salary'
  );
  const startDateField = template.fields.find(
    (f) => f.type === 'DATE'
  );

  // 4. Create document from template with prefilled data
  const documentResponse = await fetch(`${BASE_URL}/template/use`, {
    method: 'POST',
    headers: {
      Authorization: API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      templateId: 456,
      recipients: [
        {
          id: employeeRecipient.id,
          email: employeeData.email,
          name: employeeData.name,
        },
      ],
      prefillFields: [
        {
          id: positionField.id,
          type: 'text',
          value: employeeData.position,
        },
        {
          id: salaryField.id,
          type: 'number',
          value: employeeData.salary.toString(),
        },
        {
          id: startDateField.id,
          type: 'date',
          value: employeeData.startDate,
        },
      ],
      override: {
        subject: `Employment Contract for ${employeeData.name}`,
        message: `Hi ${employeeData.name},\n\nPlease review and sign your employment contract.`,
      },
      distributeDocument: false,
      externalId: `emp-contract-${Date.now()}`,
    }),
  });

  const document = await documentResponse.json();

  // 5. Distribute the envelope and get recipient signing links
  const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
    method: 'POST',
    headers: {
      Authorization: API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      envelopeId: document.envelopeId,
    }),
  });
  const distribution = await distributionResponse.json();

  return {
    envelopeId: document.envelopeId,
    signingUrl: distribution.recipients[0].signingUrl,
  };
}

// Usage
const result = await sendEmploymentContract({
  email: 'john.doe@example.com',
  name: 'John Doe',
  position: 'Senior Engineer',
  salary: 120000,
  startDate: '2025-03-01',
});

console.log('Document created:', result.envelopeId);
console.log('Signing URL:', result.signingUrl);