Schemas

`AttemptOut`

D139(d): one HTTP attempt. `signature_t` is the `t` the signature was computed with; the signature value itself is never stored.

Member	Type	Notes
`attempt` required	`integer`
`duration_ms`	`integer \| null`
`error`	`string \| null`
`response_code`	`integer \| null`
`response_excerpt`	`string \| null`
`sent_at` required	`string`
`signature_t`	`integer \| null`

`BulkRowIn`

Member	Type	Notes
`form_values`	`object of string`	Prefills keyed by field name, or by field index as a string.
`recipients` required	`array of object of any`	One entry per template placeholder, in signing position: {name, email, auth_level?}.

`BulkRowOut`

Member	Type	Notes
`delivery_state`	`string \| null`
`document_id`	`string \| null`
`error`	`string \| null`
`recipients` required	`array of object of any`
`row_no` required	`integer`
`sent_at`	`string (date-time) \| null`
`status` required	`"invalid" \| "queued" \| "sending" \| "sent" \| "failed" \| "canceled"`

`BulkSendOut`

Member	Type	Notes
`canceled_count` required	`integer`
`created_at` required	`string (date-time)`
`dispatched_at`	`string (date-time) \| null`
`failed_count` required	`integer`
`finished_at`	`string (date-time) \| null`
`id` required	`string`
`mode` required	`"live" \| "test"`
`review_flagged` required	`boolean`
`row_count` required	`integer`
`rows`	`array of BulkRowOut \| null` BulkRowOut
`sent_count` required	`integer`
`source_filename`	`string \| null`
`status` required	`"draft" \| "invalid" \| "ready" \| "dispatching" \| "done" \| "failed" \| "canceled"`
`template_id` required	`string`

`BulkSendPage`

Member	Type	Notes
`items` required	`array of BulkSendOut` BulkSendOut
`limit` required	`integer`
`offset` required	`integer`
`total` required	`integer`

`CreateBulkSendIn`

Member	Type	Notes
`rows` required	`array of BulkRowIn` BulkRowIn
`source_filename`	`string (max length 300) \| null`
`template_id` required	`string`	A tpl_… id.

`CreateDocumentReq`

Member	Type	Notes
`date_format`	`"YYYY-MM-DD" \| "MM/DD/YYYY" \| "DD/MM/YYYY" \| "D MMM YYYY" \| null`	How date fields are written into the signed PDF. One of the listed values; any other value is a 422.
`display_timezone`	`string \| null`	IANA time zone name used to show dates and times to signers and on the Certificate of Completion, such as `America/New_York` or `UTC`. Matched exactly, including case. Display only: storage is UTC. Any other value is a 422.
`expires_at`	`string (date-time) \| null`
`fields`	`array of FieldSpec` FieldSpec
`locale`	`string \| null`	Default language for the signing ceremony, as a language subtag (`en`). A default, not an assignment: the signer can choose a different language themselves before they consent, and their choice wins. Only languages whose legal text has been reviewed are accepted; anything else is a 422. Omit it and the signer's own browser decides.
`message`	`string \| null`
`recipients`	`array of RecipientSpec` RecipientSpec	Each person appears once per role: two recipients with the same email and the same role are a 422, here and at `PUT /documents/{id}/recipients`. One address may hold different roles (a signer who is also `cc`).
`redirect_url`	`string \| null`	Where the signer is sent after finishing. Must be an `https://` URL (D20); anything else is a 422 here, not a failure later.
`reminder_cadence_days`	`integer (>= 1) \| null`
`title` required	`string (min length 1, max length 300)`
`visibility`	`"everyone" \| "managers"`	Default `"everyone"`.

`CreateKeyReq`

Member	Type	Notes
`mode`	`string (pattern ^(live\|test)$)`	Default `"live"`.
`name` required	`string (min length 1, max length 120)`

`CreateTemplateIn`

Member	Type	Notes
`fields`	`array of FieldSpec` FieldSpec
`folder_id`	`string (uuid) \| null`	A template folder of this workspace (`GET /folders?kind=templates`). A document folder is refused.
`name` required	`string (min length 1, max length 300)`
`pdf_base64` required	`string`
`recipients`	`array of RecipientSpec` RecipientSpec

`CreateWebhookReq`

Member	Type	Notes
`events`	`array of string`
`url` required	`string (max length 2000)`

`DeliveryDetailOut`

D139(d): the listing row plus the payload as posted and every attempt.

Member	Type	Notes
`attempt` required	`integer`
`attempts` required	`array of AttemptOut` AttemptOut
`created_at` required	`string`
`delivered_at`	`string \| null`
`endpoint_id` required	`string (uuid)`
`event_type` required	`string`
`id` required	`integer`
`last_error`	`string \| null`
`next_retry_at`	`string \| null`
`payload` required	`object of any`
`response_code`	`integer \| null`
`status` required	`string`

`DeliveryOut`

Member	Type	Notes
`attempt` required	`integer`
`created_at` required	`string`
`delivered_at`	`string \| null`
`event_type` required	`string`
`id` required	`integer`
`last_error`	`string \| null`
`next_retry_at`	`string \| null`
`response_code`	`integer \| null`
`status` required	`string`

`DeviceCodeOut`

Member	Type	Notes
`device_code` required	`string`
`expires_in` required	`integer`
`interval` required	`integer`
`user_code` required	`string`
`verification_uri` required	`string`
`verification_uri_complete` required	`string`

`DeviceCodeReq`

Member	Type	Notes
`client` required	`string (pattern ^[a-z][a-z0-9-]{0,31}$)`	e.g. senv
`client_version`	`string (max length 64) \| null`
`mode`	`"live" \| "test"`	Default `"live"`.
`name`	`string (max length 100) \| null`	Name for the key the human approves

`DeviceTokenOut`

Member	Type	Notes
`api_key` required	`string`
`display` required	`string`
`key_id` required	`string (uuid)`
`mode` required	`string`
`name` required	`string`
`tenant_slug` required	`string`

`DeviceTokenReq`

Member	Type	Notes
`device_code` required	`string (min length 16, max length 128)`

`DocumentOut`

Member	Type	Notes
`completed_at`	`string (date-time) \| null`
`created_at` required	`string (date-time)`
`date_format`	`string \| null`
`delivery_problem`	`boolean`	Default `false`.
`display_timezone`	`string \| null`
`expires_at`	`string (date-time) \| null`
`fields`	`array of FieldOut` FieldOut
`folder_id`	`string (uuid) \| null`
`id` required	`string`	Public document id, `doc_…`
`locale`	`string \| null`	The default signing-ceremony language set on this document, if any. Not the language a signer chose: that is theirs, and it appears on the document's event trail rather than here.
`message`	`string \| null`
`mode` required	`"live" \| "test"`
`original_sha256` required	`string`
`recipients`	`array of RecipientOut` RecipientOut
`redirect_url`	`string \| null`
`reminder_cadence_days`	`integer \| null`
`seal_profile`	`string \| null`
`sealed`	`boolean`	Default `false`.
`sent_at`	`string (date-time) \| null`
`size_bytes` required	`integer`
`source_template_id`	`string \| null`	Public id (`tpl_…`) of the template this document was made from
`status` required	`"draft" \| "sent" \| "partially_signed" \| "completed" \| "voided" \| "rejected" \| "expired"`
`subject`	`string \| null`	The invitation email's subject line, if one was set. Null means SignEnvoy's default subject.
`team_id` required	`string (uuid)`
`title` required	`string`
`visibility` required	`"everyone" \| "managers"`

`DocumentPage`

Member	Type	Notes
`items` required	`array of DocumentOut` DocumentOut
`limit` required	`integer`
`offset` required	`integer`
`total` required	`integer`

`DuplicateDocumentIn`

Member	Type	Notes
`title`	`string (min length 1, max length 300) \| null`

`DuplicateTemplateIn`

Member	Type	Notes
`name`	`string (min length 1, max length 300) \| null`

`EmbedSessionOut`

An embed session for one recipient (D88(c)). `embed_url` is the ceremony URL to put in your iframe or WebView: it works once, within `expires_at`, and opening it issues the recipient's signing link and loads the ceremony in place. Mint one per page render; a reused or late URL shows the recipient a plain "session ended" state and reports `error` on the channel `event_delivery` names.

Member	Type	Notes
`embed_url` required	`string`
`event_delivery`	`string`	Default `"message"`.
`expires_at` required	`string (date-time)`
`recipient_id` required	`string (uuid)`
`warnings`	`array of EmbedWarning \| null` EmbedWarning

`EmbedSessionReq`

How the ceremony reports its events to the page or app that opened it (D142). `message` (default): postMessage — to your page when framed, or to the ceremony's own window when a WebView loads it top-level, for a script you inject. `redirect`: on `completed`, `rejected` or `error` the ceremony navigates to `signenvoy-message://<event>?…`, which your WebView's navigation handler cancels and reads; nothing reaches the network. `none`: no events.

Member	Type	Notes
`event_delivery`	`"message" \| "redirect" \| "none"`	Default `"message"`.

`EmbedWarning`

A warning on a successful embed-session mint: the same words the refusal would carry, with where to read more and where to fix it.

Member	Type	Notes
`code` required	`string`
`detail` required	`string`
`docs_url` required	`string`
`settings_url`	`string \| null`

`EnvelopePatch`

Post-create mutable surface: display prefs, folder, visibility. Structural changes (recipients/fields) go through their own setters and are draft-only.

Member	Type	Notes
`clear_folder`	`boolean`	Default `false`.
`date_format`	`"YYYY-MM-DD" \| "MM/DD/YYYY" \| "DD/MM/YYYY" \| "D MMM YYYY" \| null`	How date fields are written into the signed PDF. One of the listed values; any other value is a 422.
`display_timezone`	`string \| null`	IANA time zone name used to show dates and times to signers and on the Certificate of Completion, such as `America/New_York` or `UTC`. Matched exactly, including case. Display only: storage is UTC. Any other value is a 422.
`folder_id`	`string (uuid) \| null`
`locale`	`string \| null`
`message`	`string (max length 1000) \| null`
`redirect_url`	`string \| null`
`reminder_cadence_days`	`integer (>= 0) \| null`
`subject`	`string (max length 200) \| null`
`visibility`	`"everyone" \| "managers" \| null`

`EventOut`

Member	Type	Notes
`actor` required	`object of any`
`created_at_iso` required	`string`
`envelope_id` required	`string`
`event_type` required	`string`
`hash` required	`string`
`ip`	`string \| null`
`payload` required	`object of any`
`payload_hash` required	`string`
`prev_hash` required	`string`
`seq` required	`integer`
`user_agent`	`string \| null`

`FairUse`

Member	Type	Notes
`burst_rps` required	`number`
`envelopes_per_day_review_threshold`	`integer`	Default `2000`.
`sustained_rps` required	`number`

`FieldOut`

Member	Type	Notes
`completed_at`	`string (date-time) \| null`
`envelope_id` required	`string`
`h` required	`number`
`id` required	`string (uuid)`
`name`	`string \| null`
`page` required	`integer`
`prefill_value`	`string \| null`
`read_only` required	`boolean`
`recipient_id` required	`string (uuid) \| null`
`required` required	`boolean`
`settings` required	`FieldSettings` FieldSettings
`type` required	`"signature" \| "initials" \| "name" \| "email" \| "date" \| "text" \| "number" \| "checkbox" \| "radio" \| "dropdown"`
`value`	`string \| null`
`w` required	`number`
`x` required	`number`
`y` required	`number`

`FieldSettings`

F-12 field settings — enforced server-side at completion.

Member	Type	Notes
`input_modes`	`array of "draw" \| "type" \| "upload" \| null`
`max_length`	`integer (>= 1) \| null`
`max_value`	`number \| null`
`min_value`	`number \| null`
`options`	`array of string \| null`
`pattern`	`string \| null`

`FieldSpec`

Member	Type	Notes
`h` required	`number (<= 1)`
`name`	`string (max length 100, pattern ^[A-Za-z][A-Za-z0-9_.-]*$) \| null`
`page` required	`integer (>= 1)`
`prefill_value`	`string \| null`
`read_only`	`boolean`	Default `false`.
`recipient_index` required	`integer (>= 0)`
`required`	`boolean`	Default `true`.
`settings`	`FieldSettings` FieldSettings
`type` required	`"signature" \| "initials" \| "name" \| "email" \| "date" \| "text" \| "number" \| "checkbox" \| "radio" \| "dropdown"`
`w` required	`number (<= 1)`
`x` required	`number (>= 0, <= 1)`
`y` required	`number (>= 0, <= 1)`

`FolderIn`

Member	Type	Notes
`kind`	`"documents" \| "templates"`	`documents` (the default) or `templates`. The parent, if any, must be a folder of the same kind. Default `"documents"`.
`name` required	`string (min length 1, max length 120)`
`parent_id`	`string (uuid) \| null`

`FolderOut`

Member	Type	Notes
`depth` required	`integer`	1 for a root folder; at most 5
`id` required	`string (uuid)`
`kind`	`"documents" \| "templates"`	Which tree the folder belongs to. Document folders hold documents; template folders hold templates. Fixed at creation. Default `"documents"`.
`name` required	`string`
`parent_id`	`string (uuid) \| null`

`FolderPatchIn`

Member	Type	Notes
`move_to_root`	`boolean`	Default `false`.
`name`	`string (min length 1, max length 120) \| null`
`parent_id`	`string (uuid) \| null`

`KeyCreated`

Member	Type	Notes
`created_at`	`string \| null`
`display` required	`string`
`expires_at`	`string \| null`
`id` required	`string (uuid)`
`key` required	`string`
`last_used_at`	`string \| null`
`mode` required	`string`
`name` required	`string`
`revoked_at`	`string \| null`

`KeyOut`

Member	Type	Notes
`created_at`	`string \| null`
`display` required	`string`
`expires_at`	`string \| null`
`id` required	`string (uuid)`
`last_used_at`	`string \| null`
`mode` required	`string`
`name` required	`string`
`revoked_at`	`string \| null`

`Me`

Member	Type	Notes
`fair_use` required	`FairUse` FairUse
`grace_until` required	`string \| null`
`key_mode` required	`string`
`plan` required	`string`
`status` required	`string`
`tenant_slug` required	`string`
`usage` required	`Usage` Usage

`MintedLinkOut`

A signing link minted for one recipient (D86(e)). The URL is the ceremony; embed it, redirect to it, or deliver it yourself. It is returned exactly once — the token is stored hashed.

Member	Type	Notes
`email` required	`string`
`expires_at` required	`string (date-time)`
`recipient_id` required	`string (uuid)`
`signing_url` required	`string`

`PatchTemplateIn`

D54: every part given replaces the stored one; absent parts stay.

Member	Type	Notes
`clear_folder`	`boolean`	Take the template out of its folder. Default `false`.
`fields`	`array of FieldSpec \| null` FieldSpec
`folder_id`	`string (uuid) \| null`	Move the template into this template folder.
`name`	`string (min length 1, max length 300) \| null`
`recipients`	`array of RecipientSpec \| null` RecipientSpec

`PatchWebhookReq`

D58(a): every member optional; `active: true` re-enables a disabled endpoint (the only way back from `/disable` short of recreating it).

Member	Type	Notes
`active`	`boolean \| null`
`events`	`array of string \| null`
`url`	`string (max length 2000) \| null`

`PingOut`

Member	Type	Notes
`event_id` required	`string`
`id` required	`integer`
`status` required	`string`

`ProblemDetails`

RFC 9457 error. Branch on type; additional members depend on the problem type.

Member	Type	Notes
`detail`	`string`
`docs_url` required	`string (uri)`
`instance` required	`string`
`status` required	`integer`
`title` required	`string`
`type` required	`string`

`RecipientOut`

Member	Type	Notes
`auth_level` required	`"link" \| "otp"`
`completed_at`	`string (date-time) \| null`
`consent_at`	`string (date-time) \| null`
`email` required	`string`
`email_normalized` required	`string`
`envelope_id` required	`string`
`id` required	`string (uuid)`
`name` required	`string`
`reassigned_from`	`string (uuid) \| null`
`reject_reason`	`string \| null`
`rejected_at`	`string (date-time) \| null`
`role` required	`"signer" \| "approver" \| "viewer" \| "cc"`
`signing_order` required	`integer`
`status` required	`"pending" \| "sent" \| "opened" \| "completed" \| "rejected" \| "reassigned"`

`RecipientSpec`

Member	Type	Notes
`auth_level`	`"link" \| "otp"`	Default `"link"`.
`email` required	`string (email)`
`name` required	`string (min length 1, max length 200)`
`role`	`"signer" \| "approver" \| "viewer" \| "cc"`	Default `"signer"`.
`signing_order`	`integer (>= 1)`	Default `1`.

`RedeliverOut`

Member	Type	Notes
`id` required	`integer`
`status` required	`"queued"`

`ReplayIn`

D139(e): re-queue deliveries created in [since, until).

Member	Type	Notes
`since` required	`string (date-time)`
`status`	`"dead" \| "all"`	Default `"dead"`.
`until`	`string (date-time) \| null`

`ReplayOut`

Member	Type	Notes
`queued` required	`integer`

`SendOut`

Member	Type	Notes
`id` required	`string`
`recipients`	`array of MintedLinkOut` MintedLinkOut
`status` required	`"sent"`

`SendReq`

Member	Type	Notes
`delivery`	`"email" \| "none"`	Default `"email"`.
`message`	`string \| null`

`TemplateOut`

Member	Type	Notes
`created_at` required	`string (date-time)`
`fields`	`array of FieldSpec` FieldSpec
`folder_id`	`string (uuid) \| null`
`id` required	`string`	Public template id, `tpl_…`
`name` required	`string`
`recipients`	`array of RecipientSpec` RecipientSpec
`sha256` required	`string`
`team_id` required	`string (uuid)`
`updated_at`	`string (date-time) \| null`
`version`	`integer`	Default `1`.

`TemplatePage`

Member	Type	Notes
`items` required	`array of TemplateOut` TemplateOut
`limit` required	`integer`
`offset` required	`integer`
`total` required	`integer`

`Usage`

D91 as amended by D105: what this period has cost so far. `minimum_cents`, `included_at_minimum` and `rate_cents` are this workspace's EFFECTIVE terms for this period: finance's agreed price if it has one, and prorated in the calendar month it went live. The bill is `minimum_cents + max(0, used - included_at_minimum) * rate_cents`, and `bill_cents` / `true_up_cents` already carry it: read them rather than computing, because the formula is not `max(minimum, used x rate)` and a client that assumes it will be wrong at the crossing. `included_at_minimum` is also the number D106(b)'s cancellation cap uses, so the count shown here is the count enforced. D96: `used` counts envelopes that **completed** in this period, not ones sent in it. An envelope sent today and signed next month is next month's number, and one nobody signs is never anybody's — so this understates what the period will eventually cost, which is the honest direction for a running total to be wrong in. Sandbox envelopes are not counted here (D92): a test key's usage is always zero, which is the honest answer, not a missing one.

Member	Type	Notes
`bill_cents` required	`integer`
`included_at_minimum` required	`integer`
`minimum_cents` required	`integer`
`rate_cents` required	`integer`
`resets_on` required	`string`
`true_up_cents` required	`integer`
`used` required	`integer`

`UseTemplateIn`

Member	Type	Notes
`date_format`	`"YYYY-MM-DD" \| "MM/DD/YYYY" \| "DD/MM/YYYY" \| "D MMM YYYY" \| null`	How date fields are written into the signed PDF. One of the listed values; any other value is a 422.
`display_timezone`	`string \| null`	IANA time zone name used to show dates and times to signers and on the Certificate of Completion, such as `America/New_York` or `UTC`. Matched exactly, including case. Display only: storage is UTC. Any other value is a 422.
`form_values`	`object of string`	Prefill values keyed by field name, or by field index as a string in the template's field order ("0", "1", …). An unknown key fails the request with 422.
`recipients` required	`array of RecipientSpec` RecipientSpec
`redirect_url`	`string \| null`	Where the signer is sent after finishing. Must be an `https://` URL (D20); anything else is a 422 here, not a failure later.
`title`	`string (min length 1, max length 300) \| null`

`VoidOut`

Member	Type	Notes
`id` required	`string`
`status` required	`"voided"`

`VoidReq`

Member	Type	Notes
`reason` required	`string (min length 1, max length 1000)`

`WebhookCreated`

Member	Type	Notes
`active` required	`boolean`
`disabled_at`	`string \| null`
`disabled_reason`	`string \| null`
`events` required	`array of string`
`failing_since`	`string \| null`
`id` required	`string (uuid)`
`last_failure_at`	`string \| null`
`last_success_at`	`string \| null`
`previous_secret_expires_at`	`string \| null`
`secret` required	`string`
`url` required	`string`

`WebhookOut`

Member	Type	Notes
`active` required	`boolean`
`disabled_at`	`string \| null`
`disabled_reason`	`string \| null`
`events` required	`array of string`
`failing_since`	`string \| null`
`id` required	`string (uuid)`
`last_failure_at`	`string \| null`
`last_success_at`	`string \| null`
`previous_secret_expires_at`	`string \| null`
`url` required	`string`