EnvelopeCreated

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/inkseal-net/json-schema/inkseal-net-envelope-created-schema.json",
  "title": "EnvelopeCreated",
  "description": "The immutable response captured at creation. Template provenance and readiness reflect the original snapshot, even when replayed later.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/inkseal-net-openapi.json#/components/schemas/EnvelopeCreated",
  "type": "object",
  "required": [
    "id",
    "status",
    "subject",
    "signingOrder",
    "template",
    "signers",
    "fields",
    "readiness",
    "send",
    "expiresAt",
    "createdAt",
    "steps",
    "cc",
    "creditCost",
    "creditLines",
    "attachments"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Public envelope id. This is the `envelopeId` path parameter for every later call on this envelope: `POST /envelopes/{envelopeId}/send`, `GET /envelopes/{envelopeId}`, `GET /envelopes/{envelopeId}/document`, and `GET /envelopes/{envelopeId}/audit-trail`."
    },
    "status": {
      "$ref": "#/$defs/EnvelopeStatus"
    },
    "subject": {
      "type": [
        "string",
        "null"
      ]
    },
    "signingOrder": {
      "type": "string",
      "enum": [
        "parallel",
        "sequential"
      ]
    },
    "template": {
      "$ref": "#/$defs/EnvelopeTemplateProvenance"
    },
    "signers": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SignerSummary"
      }
    },
    "fields": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FieldSummary"
      }
    },
    "readiness": {
      "$ref": "#/$defs/EnvelopeReadiness"
    },
    "send": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "requested",
        "status"
      ],
      "properties": {
        "requested": {
          "type": "boolean"
        },
        "status": {
          "type": "string",
          "enum": [
            "not_requested",
            "scheduled"
          ],
          "description": "`scheduled` means the durable send intent committed. Queue transport is recovered asynchronously."
        }
      }
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "warnings": {
      "type": "array",
      "description": "Non-blocking remarks about this envelope, currently recipient domains this workspace has never sent to. Empty when there is nothing to say. Absent on a response replayed from before this field existed.",
      "items": {
        "$ref": "#/$defs/EnvelopeWarning"
      }
    },
    "steps": {
      "type": "array",
      "description": "The routing chain as persisted. A parallel envelope is a single step holding every signer.",
      "items": {
        "$ref": "#/$defs/EnvelopeSigningStep"
      }
    },
    "cc": {
      "type": "array",
      "description": "Copy recipients on this envelope.",
      "items": {
        "$ref": "#/$defs/CcRecipientSummary"
      }
    },
    "creditCost": {
      "type": "integer",
      "description": "Credits sending this envelope costs: one for the envelope, one for each signer who is not the sender, and one more when `emailVerification` is on. An unmetered workspace is quoted the same price and charged nothing."
    },
    "creditLines": {
      "type": "array",
      "description": "The same total broken into its lines.",
      "items": {
        "$ref": "#/$defs/CreditLine"
      }
    },
    "attachments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EnvelopeAttachment"
      },
      "description": "Unsigned files carried by signing request emails, in caller order."
    }
  },
  "$defs": {
    "CcRecipientSummary": {
      "type": "object",
      "additionalProperties": false,
      "description": "A copy recipient as stored on the envelope.",
      "required": [
        "id",
        "name",
        "email"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "format": "email"
        }
      }
    },
    "CreditLine": {
      "type": "object",
      "description": "One line of what an envelope costs to send. The envelope line is always present; a signer line appears when the envelope has signers the workspace pays for, and an `otp` line when it asks for a one-time code.",
      "required": [
        "kind",
        "quantity",
        "unitCredits",
        "credits"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "envelope",
            "signer",
            "otp"
          ]
        },
        "quantity": {
          "type": "integer",
          "description": "How many units this line charges for."
        },
        "unitCredits": {
          "type": "integer",
          "description": "Credits per unit."
        },
        "credits": {
          "type": "integer",
          "description": "`quantity` times `unitCredits`."
        }
      }
    },
    "EnvelopeAttachment": {
      "type": "object",
      "required": [
        "id",
        "filename",
        "contentType",
        "sizeBytes"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "filename": {
          "type": "string"
        },
        "contentType": {
          "type": "string"
        },
        "sizeBytes": {
          "type": "integer"
        }
      }
    },
    "EnvelopeReadiness": {
      "type": "object",
      "description": "Computed send readiness. It is never persisted and may change after a draft edit.",
      "required": [
        "canSend",
        "issues"
      ],
      "properties": {
        "canSend": {
          "type": "boolean",
          "description": "True when no readiness issue blocks sending. Credit availability is separate."
        },
        "issues": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ReadinessIssue"
          }
        }
      }
    },
    "EnvelopeSigningStep": {
      "type": "object",
      "additionalProperties": false,
      "description": "One step of the routing chain. Everyone in it is emailed together.",
      "required": [
        "step",
        "signers"
      ],
      "properties": {
        "step": {
          "type": "integer",
          "minimum": 1
        },
        "status": {
          "type": "string",
          "enum": [
            "completed",
            "active",
            "pending"
          ],
          "description": "Where this step sits relative to the step the envelope is on."
        },
        "signers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Public ids of the signers in this step."
        }
      }
    },
    "EnvelopeStatus": {
      "type": "string",
      "description": "Where the envelope is in its lifecycle. `sending` and `completing` are transient; `completed`, `declined`, `voided`, and `expired` are terminal.",
      "enum": [
        "draft",
        "sending",
        "pending",
        "completing",
        "completed",
        "declined",
        "voided",
        "expired"
      ]
    },
    "EnvelopeTemplateProvenance": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "id",
        "version"
      ],
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Null after the source template is deleted."
        },
        "version": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "EnvelopeWarning": {
      "type": "object",
      "description": "A remark about a created envelope. Never a refusal: the envelope exists either way, and the warning is something worth confirming with a person before sending.",
      "required": [
        "code",
        "message",
        "domains"
      ],
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "unfamiliar_recipient_domain"
          ],
          "description": "`unfamiliar_recipient_domain`: a signer is at a domain this workspace has never sent an envelope to."
        },
        "message": {
          "type": "string",
          "description": "The warning in one sentence, written to be repeated to a person."
        },
        "domains": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The recipient domains this workspace has not sent to before."
        }
      }
    },
    "FieldSummary": {
      "type": "object",
      "description": "A field as the create response carries them: enough to correlate the ids the server minted with the fields that were requested.",
      "required": [
        "id",
        "type",
        "name",
        "assignee",
        "readonly",
        "value",
        "pageIndex"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Public field id."
        },
        "type": {
          "$ref": "#/$defs/FieldType"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Stable field name when one was supplied."
        },
        "assignee": {
          "type": "string",
          "enum": [
            "sender",
            "signer"
          ]
        },
        "readonly": {
          "type": "boolean"
        },
        "value": {
          "type": [
            "string",
            "null"
          ],
          "description": "Initial sender value or signer default."
        },
        "pageIndex": {
          "type": "integer",
          "minimum": 0,
          "description": "0-based page the field sits on."
        }
      }
    },
    "FieldType": {
      "type": "string",
      "description": "How the field is filled and rendered. Values are stored as strings; signature and initials use images.",
      "enum": [
        "signature",
        "initials",
        "text",
        "date",
        "checkbox",
        "number",
        "email",
        "select",
        "radio",
        "textarea"
      ]
    },
    "InvalidSenderValueIssue": {
      "type": "object",
      "required": [
        "code",
        "fieldId",
        "name",
        "detail"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_sender_value"
          ]
        },
        "fieldId": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "detail": {
          "type": "string",
          "description": "Safe, human-readable validation detail."
        }
      }
    },
    "MissingSenderValueIssue": {
      "type": "object",
      "required": [
        "code",
        "fieldId",
        "name",
        "label"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "missing_sender_value"
          ]
        },
        "fieldId": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "label": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "NoSignerFieldsIssue": {
      "type": "object",
      "required": [
        "code"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "no_signer_fields"
          ]
        }
      }
    },
    "ReadinessIssue": {
      "oneOf": [
        {
          "$ref": "#/$defs/MissingSenderValueIssue"
        },
        {
          "$ref": "#/$defs/InvalidSenderValueIssue"
        },
        {
          "$ref": "#/$defs/UnassignedFieldIssue"
        },
        {
          "$ref": "#/$defs/NoSignerFieldsIssue"
        }
      ]
    },
    "SignerRole": {
      "type": "string",
      "description": "What the recipient is asked to do. `signer` executes the document and must be assigned at least one field. `approver` approves or declines and may hold fields. `reviewer` acknowledges having read it and may hold none. Defaults to `signer`.",
      "enum": [
        "signer",
        "approver",
        "reviewer"
      ]
    },
    "SignerStatus": {
      "type": "string",
      "description": "Where one recipient is. `pending` means not yet invited, which on a sequential envelope is normal for everyone behind the current turn. `signed`, `approved` and `acknowledged` are the three positive terminal states, one per role: a signer signs, an approver approves, a reviewer acknowledges.",
      "enum": [
        "pending",
        "sent",
        "viewed",
        "signed",
        "approved",
        "acknowledged",
        "declined"
      ]
    },
    "SignerSummary": {
      "type": "object",
      "description": "A signer as the list and create responses carry them.",
      "required": [
        "id",
        "name",
        "email",
        "role",
        "status",
        "roleKey"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Public signer id."
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "role": {
          "$ref": "#/$defs/SignerRole"
        },
        "status": {
          "$ref": "#/$defs/SignerStatus"
        },
        "roleKey": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[a-z][a-z0-9_]{0,31}$",
          "description": "Key of the template role this signer was created for, such as `client`. Null when the envelope was not created from a template or public link, and for signers added to it afterwards. Distinct from `role`, which is what the recipient is asked to do."
        }
      }
    },
    "UnassignedFieldIssue": {
      "type": "object",
      "description": "Reserved for forward compatibility. Current persisted envelopes do not produce this issue.",
      "required": [
        "code",
        "fieldId"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "unassigned_field"
          ]
        },
        "fieldId": {
          "type": "string"
        }
      }
    }
  }
}