Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Email 2FA Verification

Email 2FA adds an extra layer of identity verification to the signing process. When enabled on a template, signers must verify their email address by entering a one-time code before they can access the signing form.

​
How it works

  1. A signer opens the signing link (/s/:slug).
  2. Instead of seeing the signing form immediately, they see an email verification screen.
  3. DocuTrust sends a 6-digit verification code to the signer’s email address.
  4. The signer enters the code on the verification screen.
  5. If the code is valid, the signer proceeds to the signing form.
  6. If the code is invalid or expired, the signer can request a new one.

​
Enabling Email 2FA

​
Per-template configuration

Enable email 2FA verification on a template by setting the require_email_2fa preference: 
curl -X PUT "$DOCUTRUST_URL/api/templates/42" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "require_email_2fa": true
    }
  }'
Response: 
{
  "id": 42,
  "name": "Service Agreement",
  "slug": "qk7x9m2p",
  "external_id": "contract-sa-2026",
  "folder_name": "Legal Contracts",
  "source": "builder",
  "shared": true,
  "field_count": 8,
  "submitter_count": 2,
  "schema": [],
  "submitters": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Client"
    },
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Company Representative"
    }
  ],
  "preferences": {
    "require_email_2fa": true
  },
  "thumbnail_url": "/api/templates/42/documents/thumbnail",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-09T10:15:00.000Z"
}

​
Disabling Email 2FA

Set require_email_2fa to false: 
curl -X PUT "$DOCUTRUST_URL/api/templates/42" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "require_email_2fa": false
    }
  }'

​
Verification flow

When a signer opens their signing URL and the template has require_email_2fa: true, they see an email verification screen instead of the signing form. The screen displays:
  • A message explaining that email verification is required.
  • The signer’s email address (partially masked for privacy, e.g., j***@example.com).
  • A button to send the verification code.

​
Step 2: Code delivery

DocuTrust sends an email containing:
  • A 6-digit numeric verification code.
  • The template name for context.
  • An expiration notice (codes expire after 10 minutes).
Example email: 
Subject: Your verification code for Service Agreement

Your DocuTrust verification code is:

  847291

This code expires in 10 minutes.

If you did not request this code, you can safely ignore this email.

​
Step 3: Code entry

The signer enters the 6-digit code on the verification screen. Validation rules:
RuleBehavior
Correct codeThe signer is redirected to the signing form.
Incorrect codeAn error message is shown. The signer can retry.
Expired code (after 10 minutes)An error message is shown with an option to resend a new code.
Too many failed attempts (5 attempts)The signer is temporarily locked out for 15 minutes.

​
Step 4: Signing form access

After successful verification, the signer proceeds to the normal signing form. The verification status is stored in the submitter’s session — the signer does not need to re-verify if they navigate away and return within the same browser session.

​
Audit trail

Email 2FA verification events are recorded in the immutable audit trail:
EventDescription
email_2fa_code_sentA verification code was sent to the signer’s email.
email_2fa_code_verifiedThe signer entered a valid verification code.
email_2fa_code_failedThe signer entered an invalid verification code.
email_2fa_code_expiredA verification code expired without being used.
email_2fa_lockoutThe signer was temporarily locked out after too many failed attempts.
email_2fa_code_resentA new verification code was resent after the previous one expired or was requested again.
Audit log entry example: 
{
  "event": "email_2fa_code_verified",
  "timestamp": "2026-04-09T14:22:00.000Z",
  "actor": "jane@example.com",
  "ip_address": "198.51.100.22",
  "details": {
    "submitter_id": 301,
    "submitter_email": "jane@example.com",
    "code_sent_at": "2026-04-09T14:20:00.000Z",
    "verified_at": "2026-04-09T14:22:00.000Z",
    "attempts": 1,
    "submission_id": 187,
    "template_id": 42
  }
}

​
Combining with other verification methods

Email 2FA can be combined with other verification methods for multi-layer identity verification:
CombinationFlow
Email 2FA + SMS OTPSigner verifies email first, then verifies phone via SMS OTP on a phone_verification field.
Email 2FA + KBASigner verifies email first, then answers knowledge-based authentication questions.
Email 2FA + QESSigner verifies email first, then completes Qualified Electronic Signature verification.
Email 2FA verification applies to all submitters on the template, regardless of role. If you want different verification requirements per role, create separate templates for each role with different preferences.
Email 2FA is especially useful for templates where the signer’s identity must be confirmed but you do not want the friction of phone-based verification. It adds a layer of assurance that the person accessing the form controls the email address on file.
Email 2FA requires that submitters have a valid email address. Submissions created with send_email: false still require email verification if the template has require_email_2fa: true.