Email Code Authentication

With email code authentication, SignatureAPI sends recipients an email containing a 9-digit verification code. Recipients must enter this code to authenticate and access the signing ceremony.

​

When to Use

Email code authentication provides an alternative to email link authentication when you need more control over the ceremony URL. Like email link authentication, it authenticates recipients via email, but instead of clicking a link, recipients enter a verification code.

It’s particularly useful when:

• You want to obtain the ceremony URL to share via your own channels (SMS, app notifications, etc.)
• Recipients are in environments where email links might be blocked by security policies
• You need to embed the ceremony in your application while still using email-based authentication
• You prefer a code-entry workflow over link-clicking for user experience reasons

This method combines email-based authentication with the flexibility of having direct access to the ceremony URL.

​

How It Works

1. You create an envelope with recipients set to manual ceremony creation
2. You create a ceremony with email_code authentication and receive a ceremony URL
3. You share the ceremony URL with recipients (via your own channels or by directing them to it)
4. When recipients access the ceremony URL, SignatureAPI sends them an email with a 9-digit verification code
5. Recipients enter the code in the signing ceremony to authenticate
6. Once verified, recipients can complete the signing process

​

Ceremony Creation

To use email code authentication, you must create ceremonies manually. Set the recipient’s ceremony_creation to manual when creating the envelope.

// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "title": "Service Agreement",
    "documents": [
        //...
    ],
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "ceremony_creation": "manual"
        }
    ]
}

After creating the envelope, use the recipient ID to create a ceremony with email code authentication:

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremony
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "authentication": [
        {
            "type": "email_code"
        }
    ]
}

The response includes the ceremony URL that you can share with recipients:

// HTTP Status Code 201

{
    //...
    "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
}

​

Signer Experience

The recipient can access the ceremony through various methods:

• Clicking a link in an email sent by SignatureAPI (when combined with email link authentication)
• Visiting a URL shared through your application (email, SMS, or direct link)
• Being redirected from your application
• Using an embedded ceremony within your application

Email Verification Process

When recipients access the ceremony, they’ll be prompted to verify their email address:

After clicking the verification button, SignatureAPI sends an email containing the 9-digit verification code:

Code Entry and Verification

Recipients must enter the verification code in the ceremony interface:

Once the correct code is entered, recipients can proceed with the signing ceremony:

​

Combine Authentication Methods

You can combine email code authentication with other methods for enhanced security:

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremony
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "authentication": [
        {
            "type": "custom",
            // other custom authentication properties
        },
        {
            "type": "email_code"
        }
    ]
}

​

Next Steps

• Review recipient authentication to understand available authentication methods
• Explore ceremony embedding to integrate signing directly into your application