{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/asap-cool/json-schema/asap-cool-envelope-view-schema.json",
  "title": "EnvelopeView",
  "description": "Public projection of an [`Envelope`] with its signers and audit chain.\n`document_hash` is surfaced as hex; secrets are never present.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/asap-cool-openapi.json#/components/schemas/EnvelopeView",
  "type": "object",
  "required": [
    "id",
    "status",
    "source_kind",
    "routing_mode",
    "assurance_level",
    "consent_text_version",
    "labels",
    "cc_recipients",
    "reminder_max_count",
    "reminder_count",
    "has_proof",
    "has_signed_document",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "assurance_level": {
      "type": "string",
      "description": "Targeted assurance level."
    },
    "audit_chain": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/AuditEventView"
      },
      "description": "The audit chain (present on `get`, omitted elsewhere)."
    },
    "cc_recipients": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Addresses copied on the completion notification (Cc; may be empty)."
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When every signer signed (RFC3339)."
    },
    "consent_text_version": {
      "type": "string",
      "description": "Consent-text version presented to signers."
    },
    "created_at": {
      "type": "string",
      "description": "Creation timestamp (RFC3339)."
    },
    "document_hash": {
      "type": [
        "string",
        "null"
      ],
      "description": "SHA-256 of the frozen document (hex), set at send time."
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the envelope (and its tokens) expire (RFC3339)."
    },
    "has_proof": {
      "type": "boolean",
      "description": "Whether a proof bundle is available for download."
    },
    "has_signed_document": {
      "type": "boolean",
      "description": "Whether a signed composited document (source + stamped signatures) is\navailable for download (positioned-field envelopes only)."
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Stable identifier."
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form labels for organizing / filtering (may be empty)."
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional request-email message."
    },
    "reminder_count": {
      "type": "integer",
      "format": "int32",
      "description": "How many automatic reminders have fired so far."
    },
    "reminder_interval_hours": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int32",
      "description": "Delay between two automatic reminders, in hours (`null` = default cadence)."
    },
    "reminder_max_count": {
      "type": "integer",
      "format": "int32",
      "description": "How many automatic reminders may fire over the envelope's lifetime."
    },
    "reply_to": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional `Reply-To` for the signature-request email."
    },
    "routing_mode": {
      "type": "string",
      "description": "Routing mode."
    },
    "sender_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional `From` display name for the signature-request email."
    },
    "signers": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/SignerView"
      },
      "description": "Signers on the envelope (present on `get`/`create`, omitted on `list`)."
    },
    "source_document_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Logical reference to the signed document."
    },
    "source_kind": {
      "type": "string",
      "description": "What the envelope wraps."
    },
    "status": {
      "type": "string",
      "description": "Lifecycle status."
    },
    "subject": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional request-email subject."
    },
    "updated_at": {
      "type": "string",
      "description": "Last-update timestamp (RFC3339)."
    }
  },
  "$defs": {
    "AuditEventView": {
      "type": "object",
      "description": "Public projection of an [`AuditEvent`]. Hashes are lowercase hex so a\nclient can re-verify the chain.",
      "required": [
        "id",
        "seq_index",
        "event_type",
        "event_data",
        "content_hash",
        "occurred_at"
      ],
      "properties": {
        "content_hash": {
          "type": "string",
          "description": "SHA-256 of the canonical content (hex)."
        },
        "event_data": {
          "description": "Structured payload."
        },
        "event_type": {
          "type": "string",
          "description": "Event kind."
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Stable identifier."
        },
        "occurred_at": {
          "type": "string",
          "description": "When the event occurred (RFC3339)."
        },
        "prev_hash": {
          "type": [
            "string",
            "null"
          ],
          "description": "Previous link's content hash (hex), `None` at genesis."
        },
        "seq_index": {
          "type": "integer",
          "format": "int64",
          "description": "0-based position in the chain.",
          "minimum": 0
        },
        "signer_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "Signer the event concerns, if any."
        }
      }
    },
    "SignerView": {
      "type": "object",
      "description": "Public projection of a [`Signer`]. Never carries `access_token_hash` or\n`otp_hash` (secrets stay server-side).",
      "required": [
        "id",
        "email",
        "routing_order",
        "status",
        "otp_attempts",
        "verification_method",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "consent_given_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the signer gave consent (RFC3339)."
        },
        "created_at": {
          "type": "string",
          "description": "Creation timestamp (RFC3339)."
        },
        "email": {
          "type": "string",
          "description": "Signer email."
        },
        "full_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional full name."
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Stable identifier."
        },
        "otp_attempts": {
          "type": "integer",
          "format": "int32",
          "description": "Number of failed OTP attempts on the current challenge.",
          "minimum": 0
        },
        "phone": {
          "type": [
            "string",
            "null"
          ],
          "description": "Phone (E.164) for SMS OTP, if set."
        },
        "routing_order": {
          "type": "integer",
          "format": "int32",
          "description": "Position in a sequential order (0-based)."
        },
        "signed_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the signer signed (RFC3339)."
        },
        "signed_ip": {
          "type": [
            "string",
            "null"
          ],
          "description": "Source IP captured at signing."
        },
        "status": {
          "type": "string",
          "description": "Per-signer status."
        },
        "token_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the access token expires (RFC3339), if issued."
        },
        "updated_at": {
          "type": "string",
          "description": "Last-update timestamp (RFC3339)."
        },
        "verification_method": {
          "type": "string",
          "description": "Identity-verification method."
        }
      }
    }
  }
}