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}/ceremonies
// 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:
Email verification prompt
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.
Code Entry and Verification
Recipients must enter the verification code in the ceremony interface:
Code entry interface
Once the correct code is entered, recipients can proceed with the signing ceremony:
Successful verification

​
Combine Authentication Methods

You can combine email code authentication with other methods for enhanced security: 
// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

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

​
Next Steps