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

You create an envelope with Email Code authentication configured for the recipient ceremony. In the response, you get the ceremony URL that you can share with recipients via your own channels (SMS, app notifications, direct links, etc.). Then, when recipients access the ceremony URL, SignatureAPI sends them an email with a 9-digit verification code. Recipients must enter this code to authenticate and access the signing ceremony. Check the Signer Experience section for more details.

​
Ceremony Creation

You can create an email link ceremony automatically when you create a ceremony, or manually at a later time.

​
On Envelope Creation (Automatic)

When creating an envelope, configure the recipient’s ceremony to use email code authentication. This automatically creates the ceremony and provides you with the ceremony URL in the response.
Email Code Ceremony on Envelope Creation (Request)
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "title": "Service Agreement",
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "ceremony": {
                "authentication": [
                    {
                        "type": "email_code"
                    }
                ]
                // optional properties: redirect_url, url_variant, embeddable_in, etc ...
            }
            //...
        }
    ],
    // ...
}
Email Code Ceremony on Envelope Creation (Response)
{
    "id": "abcdef12-3456-7890-1234-abcdef123456",
    "title": "Service Agreement",
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "ceremony": {
                "authentication": [
                    {
                        "type": "email_code"
                    }
                ],
                "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
                //... 
            }
            //...
        }
    ],
    //...
}
The ceremony.url property is the ceremony URL that you can share with recipients via your own channels (SMS, app notifications, direct links, etc).

​
Create Ceremony Endpoint (Manual)

To manually create an email code ceremony, use the Create Ceremony endpoint.
When you create a new ceremony for a recipient, any previous ceremonies are automatically revoked. This ensures that only the most recent ceremony remains active and accessible.
Create Email Code Ceremony (Request)
// POST https://api.signatureapi.com/v1/recipients/rec_123/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "email_code"
    }
  ]
  // optional properties: redirect_url, url_variant, embeddable_in, etc ...
}
Create Email Code Ceremony (Response)
{
  "authentication": [
    {
      "type": "email_code"
    }
  ],
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
  //... 
}
The url property is the ceremony URL that you can share with recipients via your own channels (SMS, app notifications, direct links, etc).

​
Signer Experience

Recipients can access the ceremony through various methods, depending on how you share the ceremony URL:
  • Visiting a URL shared through your application (email, SMS, or direct link)
  • Being redirected from your application
  • Using an embedded ceremony within your application
1

Email Verification Process

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

Email with Code

After clicking the verification button, SignatureAPI sends an email containing the 9-digit verification code:
Email with code
Test Mode: While in test mode, no emails are sent to recipients. You can view the verification codes that would have been sent in the SignatureAPI dashboard under the ceremony details.
3

Code Entry and Verification

Recipients must enter the verification code in the ceremony interface:
Code entry interface
4

Successful Verification

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

​
Audit Log

When recipients enter the verification code, they are automatically authenticated, and SignatureAPI records the timestamp for auditing purposes. The audit log indicates when email code authentication is used:
12/31/2025 11:59:59 PM
John Doe (#7161cf07) has authenticated using a verification code sent to john⁠@example.com.