> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thesignproof.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing Flow

> How signer links work, OTP verification, consent, and what happens after signing.

## Overview

When you call `POST /v1/envelopes/{id}/send`, SignProof:

1. Generates a short-lived signed JWT for each signer (scoped to that signer + that envelope)
2. Embeds the token in a signing URL: `https://sign.thesignproof.com/sign/{token}`
3. Sends the signer an email (and SMS if a phone number was provided) with the link

Signers never create an account. The token is their only credential.

***

## The signer journey

<Steps>
  <Step title="Signer opens their link">
    The signing UI loads the document and records a `viewed` event with IP, user agent, timestamp,
    and geo.
  </Step>

  <Step title="OTP verification">
    Depending on `authMethod`, the signer receives an OTP via email or SMS and enters it to proceed.
    This proves they control the email or phone used to invite them.
  </Step>

  <Step title="E-signature consent">
    The signer reviews and accepts the e-signature disclosure ("I agree that my electronic signature
    is legally binding"). This is recorded as a `consented` event.
  </Step>

  <Step title="Signing">
    The signer draws or types their signature and completes all required fields. Each field
    completion is recorded as a `signed_field` event.
  </Step>

  <Step title="Completed">
    When all required fields are done, a `signed` event is recorded and the next signer in the
    routing order receives their invite.
  </Step>
</Steps>

***

## Auth methods

| `authMethod` | How the signer proves identity                                               |
| ------------ | ---------------------------------------------------------------------------- |
| `email_otp`  | 6-digit OTP sent to the signer's email                                       |
| `sms_otp`    | 6-digit OTP sent to the signer's phone (requires `phone` field on signer)    |
| `none`       | No OTP — link access alone is sufficient (lower assurance, use with caution) |

<Warning>
  `authMethod: none` is appropriate only for low-risk, low-value documents. For any document with
  legal or financial consequences, use `email_otp` or `sms_otp`.
</Warning>

***

## Token security

Signing tokens are:

* **Short-lived** — default TTL is 7 days (configurable per envelope via `expiresAt`)
* **Single-use** — the token is invalidated after signing completes
* **Signer-scoped** — a token for Signer A cannot be used to view or sign Signer B's fields
* **Envelope-scoped** — cannot be used on any other envelope

If a signer loses their email, you can re-send the invite:

```bash theme={null}
curl -X POST https://api.thesignproof.com/v1/envelopes/env_01HX.../resend \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "signerId": "sgn_01HX..." }'
```

This invalidates the old token and generates a new one.

***

## Events recorded

Every action in the signing flow appends a row to `signature_events` with:

| Field        | Example                                                                                 |
| ------------ | --------------------------------------------------------------------------------------- |
| `event_type` | `viewed`, `otp_sent`, `otp_verified`, `consented`, `signed_field`, `signed`, `declined` |
| `ip`         | `203.0.113.42`                                                                          |
| `user_agent` | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...`                                    |
| `geo`        | `{ "country": "CA", "region": "ON", "city": "Toronto" }`                                |
| `timestamp`  | `2026-06-19T14:32:00.000Z`                                                              |

These events are what appear on the audit certificate page in the final PDF.

***

## What happens after all signers complete

1. All signature fields are flattened into the PDF
2. A SHA-256 hash of the final document is computed → stored as `document_hash_final`
3. An audit certificate page is appended (lists all events with timestamps, IPs, and hashes)
4. A PKCS#7 digital signature is applied over the whole file (service certificate)
5. `envelope.status` → `completed`
6. A `envelope.completed` webhook event fires to your endpoint

The sealed PDF is then available at `GET /v1/envelopes/{id}/document`.

***

## Declined envelopes

A signer can decline at any point before completing. This:

* Records a `declined` event
* Sets the envelope status to `declined`
* Fires an `envelope.declined` webhook event
* Invalidates all remaining signing links

A declined envelope cannot be resumed. Create a new envelope if you need to restart the process.