{ "openapi": "3.1.0", "info": { "title": "eSignStack API", "version": "2026-10-14", "description": "eSignStack API. Workspace and platform keys only. Snake_case JSON; clients must ignore unknown fields. Dated versions receive at least 12 months retirement notice.\n\nStart with the [API quick start](\/docs\/api-authentication).\n\n## Webhooks\n\nUse the [Webhooks](\/docs\/webhooks) guide for event delivery.\n\nError codes: invalid_request, validation_failed, resource_missing, authentication_required, permission_denied, workspace_required, workspace_suspended, rate_limit_exceeded, idempotency_key_reused, idempotency_key_in_progress, api_version_unsupported, resource_conflict, correction_requires_void, export_in_progress, api_error, service_unavailable, live_key_required.\n\n## Test mode\n\nTest keys (`sk_test_\u2026`, `rk_test_\u2026`) see and change only test data, and live keys only live data: an object of the other mode is reported as `resource_missing`. Test keys can create, send and complete envelopes on any plan. Test envelopes are watermarked and count toward no allowance. SMS signer verification is refused in test mode. Brand kit, folder and filing rule changes and identity providers need a live key (`live_key_required`); folders and filing rules are shared by both modes. A test key can only create test keys.\n\n## Allowances\n\nEnvelopes sent through the API or MCP count toward the plan's API allowance; see `GET \/usage`. A send the allowance refuses is a `422 validation_failed` with `param: document` and an `error.quota` object: `quota.code` is `envelope_limit_reached` (the plan's monthly envelopes), `api_envelope_limit_reached` (the API and MCP allowance), `api_overage_unavailable` (Platform extras are paused, for example while a payment is past due) or `api_spending_cap_reached` (the Platform spending cap), and `quota.resets_at` says when it resets." }, "servers": [ { "url": "https:\/\/staging.esignstack.app\/api\/v1" } ], "security": [ { "http": [] } ], "paths": { "\/api_keys\/current": { "get": { "operationId": "v1.api_keys.current", "description": "Returns key metadata, never its secret or hash. Browser sessions cannot\nauthenticate to the API.\n\nAny API key.", "summary": "Retrieve the current API key", "tags": [ "API keys", "ApiKey" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ApiKeyApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiKeyApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/api_keys": { "get": { "operationId": "v1.api_keys.index", "description": "Keys this key's owner (workspace or platform) has issued, in the key's mode. Secrets are never\nreturned after creation.\n\nRequires the `keys:write` key ability.", "summary": "List API keys", "tags": [ "API keys", "ApiKey" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ApiKeyApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.api_keys.store", "description": "Returns the secret once. `abilities` must be explicit (no wildcards) and can't exceed the\ncalling key's own abilities (`403`); platform-only abilities (`workspaces:read`,\n`workspaces:write`, `identity_providers:write`, `login_links:write`) need a platform key. A\ntest key can only create test keys.\n\nRequires the `keys:write` key ability.", "summary": "Create an API key", "tags": [ "API keys", "ApiKey" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateApiKeyRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "`CreatedApiKeyApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreatedApiKeyApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/api_keys\/{key}": { "delete": { "operationId": "v1.api_keys.destroy", "description": "Takes effect immediately for every request made with it.\n\nRequires the `keys:write` key ability.", "summary": "Revoke an API key", "tags": [ "API keys", "ApiKey" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/audit_trail": { "get": { "operationId": "v1.envelopes.audit_trail", "description": "The same entries as the envelope's completion certificate, oldest first, for an envelope in\nany status: what happened, who did it, from which IP address and when. The full hash-chained\nrecord is in the evidence artifact. The list is one page.\n\nRequires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve an envelope's audit trail", "tags": [ "Audit" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AuditTrailEntryApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/audit_events": { "get": { "operationId": "v1.audit_events.index", "description": "What was recorded for the workspace outside envelopes, newest first: sign-ins and\nmemberships through the platform's identity provider, legal holds, retention settings,\nexports and consent disclosures. Filter with `filter[event]`. Needs the opt-in `audit:read` ability and a live key (the log has no test\nmode); entries carry IP addresses.\n\nRequires the `audit:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List the workspace activity log", "tags": [ "Audit" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "filter[event]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "Only this event, for example `legal_hold.set`", "maxLength": 100 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AuditEventApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/brand_kits": { "get": { "operationId": "v1.brand_kits.index", "description": "A workspace key sees its workspace's kit. A platform key without\n`Workspace-Id` sees the platform's default kit.\n\nRequires the `brand_kits:read` key ability.", "summary": "List brand kits", "tags": [ "Brand kits", "BrandKit" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/BrandKitApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.brand_kits.store", "description": "Each owner has at most one kit. Send `multipart\/form-data` to upload\n`logo_light` and `logo_dark` images (PNG, JPEG or WebP). Colors,\nradius and font are checked against the brand token allowlist. Live keys only: a test key\ngets `403 live_key_required`. A workspace whose plan doesn't include custom branding gets\n`403 permission_denied`.\n\nRequires the `brand_kits:write` key ability.", "summary": "Create a brand kit", "tags": [ "Brand kits", "BrandKit" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart\/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "primary_color": { "type": [ "string", "null" ], "maxLength": 7 }, "accent_color": { "type": [ "string", "null" ], "maxLength": 7 }, "radius_px": { "type": [ "integer", "null" ] }, "font": { "type": [ "string", "null" ], "enum": [ "instrument-sans", "system", "serif" ] }, "email_header": { "type": [ "string", "null" ], "maxLength": 500 }, "email_footer": { "type": [ "string", "null" ], "maxLength": 1000 }, "support_contact": { "type": [ "string", "null" ], "maxLength": 255 }, "show_powered_by": { "type": [ "boolean", "null" ] }, "logo_light": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "maxLength": 2048 }, "logo_dark": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "maxLength": 2048 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BrandKitApiResponse" } } } }, "409": { "description": "A brand kit already exists for this owner; update it instead (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/brand_kits\/effective": { "get": { "operationId": "v1.brand_kits.effective", "description": "The result of inheritance (platform default, then workspace kit). Requires a workspace context.\n\nRequires the `brand_kits:read` key ability.", "summary": "Retrieve the effective brand of the workspace", "tags": [ "Brand kits", "BrandKit" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "brand" }, "": { "type": "array", "items": {} } }, "required": [ "object", null ] } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/brand_kits\/{brandKit}": { "get": { "operationId": "v1.brand_kits.show", "description": "Requires the `brand_kits:read` key ability.", "summary": "Retrieve a brand kit", "tags": [ "Brand kits", "BrandKit" ], "parameters": [ { "name": "brandKit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`BrandKitApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BrandKitApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.brand_kits.update", "description": "Send `null` for a field to inherit it again (workspace kits inherit from the\nplatform kit). Send `remove_assets[]` with `logo_light` or `logo_dark` to delete an image.\nLive keys only (`403 live_key_required`). A workspace whose plan doesn't include custom\nbranding gets `403 permission_denied`.\n\nRequires the `brand_kits:write` key ability.", "summary": "Update a brand kit", "tags": [ "Brand kits", "BrandKit" ], "parameters": [ { "name": "brandKit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "primary_color": { "type": [ "string", "null" ], "maxLength": 7 }, "accent_color": { "type": [ "string", "null" ], "maxLength": 7 }, "radius_px": { "type": [ "integer", "null" ] }, "font": { "type": [ "string", "null" ], "enum": [ "instrument-sans", "system", "serif" ] }, "email_header": { "type": [ "string", "null" ], "maxLength": 500 }, "email_footer": { "type": [ "string", "null" ], "maxLength": 1000 }, "support_contact": { "type": [ "string", "null" ], "maxLength": 255 }, "show_powered_by": { "type": [ "boolean", "null" ] }, "logo_light": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "maxLength": 2048 }, "logo_dark": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "maxLength": 2048 }, "remove_assets": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "logo_light", "logo_dark" ] } } } } } } }, "responses": { "200": { "description": "`BrandKitApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BrandKitApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.brand_kits.destroy", "description": "Live keys only (`403 live_key_required`).\n\nRequires the `brand_kits:write` key ability.", "summary": "Delete a brand kit", "tags": [ "Brand kits", "BrandKit" ], "parameters": [ { "name": "brandKit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "brand_kit" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/consent_disclosures": { "get": { "operationId": "v1.consent_disclosures.index", "description": "Requires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List immutable versions, newest first. Paginate using before_version. Requires workspace context", "tags": [ "Consent disclosures", "ConsentDisclosure" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "before_version", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ConsentDisclosureApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.consent_disclosures.store", "description": "Requires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Publish the disclosure for future sends. Existing envelopes retain their immutable pins. Identical content reuses the current version", "tags": [ "Consent disclosures", "ConsentDisclosure" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateConsentDisclosureRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateConsentDisclosureRequest" } } } }, "responses": { "201": { "description": "`ConsentDisclosureApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ConsentDisclosureApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/consent_disclosures\/{version}": { "get": { "operationId": "v1.consent_disclosures.show", "description": "Requires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a version within the current workspace, or current for its effective disclosure", "tags": [ "Consent disclosures", "ConsentDisclosure" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ConsentDisclosureApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ConsentDisclosureApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/editor_sessions": { "post": { "operationId": "v1.editor_sessions.store", "description": "Returns a single-use URL (open it within 10 minutes) to the eSignStack editor\nfor a draft envelope (`env_\u2026`) or a template (`tpl_\u2026`). `hosted` redirects the\nbrowser to `return_url?session=\u2026&status=saved|sent|cancelled&target=\u2026` when the\nsession ends; `embedded` is framed by `parent_origin` (one of the workspace's\nallowed embed origins) and reports `esignstack:editor.*` messages instead.\n\n`capabilities` are enforced on the server for every write, and can never exceed\nthe key's own abilities: editing needs `envelopes:write` (or `templates:write`),\n`send` needs `envelopes:send`. An opened session lasts 60 minutes idle and 8 hours\nat most. The return is a UX signal, not proof: confirm with the API or webhooks.\n`actor` is the person the host says is editing; it is recorded with every change.\n\nRequires one of the `envelopes:write`, `templates:write`, `envelopes:send` key abilities.", "summary": "Create an editor session", "tags": [ "Editor sessions", "EditorSession" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "maxLength": 64 }, "mode": { "type": "string", "enum": [ "hosted", "embedded" ] }, "return_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "parent_origin": { "type": [ "string", "null" ], "maxLength": 255 }, "capabilities": { "type": "object", "properties": { "edit_documents": { "type": "boolean" }, "edit_recipients": { "type": "boolean" }, "edit_fields": { "type": "boolean" }, "send": { "type": "boolean" } } }, "actor": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "external_id": { "type": [ "string", "null" ], "maxLength": 255 } } } }, "required": [ "target", "mode", "capabilities" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EditorSessionApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "409": { "description": "Only a draft envelope can be opened in the editor (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/move": { "post": { "operationId": "v1.envelopes.move", "description": "`folder` is an envelope folder (`fdr_\u2026`), or `null` to take it out of its folder. Any status can\nbe moved. As in the app, a moved envelope is no longer filed by its filing rule.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Move an envelope to a folder", "tags": [ "Envelope actions", "EnvelopeFolder" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`MoveToFolderApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MoveToFolderApiRequest" } } } }, "responses": { "200": { "description": "A move changes an envelope, it does not create one: 200, not the POST default of 201.\n\n\n\n`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/corrections": { "post": { "operationId": "v1.envelopes.corrections.store", "description": "Requires the `envelopes:send` key ability. Platform keys must send `Workspace-Id`.", "summary": "Correct a sent envelope as revision N+1. Recipients who have not acted can be renamed or\nreassigned (`recipients`, by `id`; a new email, phone or authentication method stops their old\nlink), added to stages that have not started (`add_recipients`) or removed\n(`remove_recipients`). `documents` replaces the documents and pages, and `fields` replaces all\nfields; send them in separate corrections, documents first. Signing links survive document\nand field changes and open the new revision. Pass `expected_revision` to refuse the correction\nif someone else corrected the envelope first. Refused with `409 correction_requires_void` when\nthe change needs a signature to be undone", "tags": [ "Envelope actions", "EnvelopeAction" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`EnvelopeCorrectionApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeCorrectionApiRequest" } } } }, "responses": { "201": { "description": "`EnvelopeCorrectionApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeCorrectionApiResponse" } } } }, "409": { "description": "The change would undo a signature (`correction_requires_void`); void the envelope and send a new one. The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/preview": { "post": { "operationId": "v1.envelopes.preview", "description": "Requires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Render the draft as it is now, watermarked \"DRAFT \u2014 not for signature\", and return a link\nthat works for a short time", "tags": [ "Envelope actions", "EnvelopeAction" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`PreviewEnvelopeApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PreviewEnvelopeApiRequest" } } } }, "responses": { "201": { "description": "`EnvelopePreviewApiResponse`\n\n`EmbeddedEnvelopePreviewApiResponse`", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/EnvelopePreviewApiResponse" }, { "$ref": "#\/components\/schemas\/EmbeddedEnvelopePreviewApiResponse" } ] } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope. The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/documents": { "get": { "operationId": "v1.envelopes.documents.index", "description": "Requires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "The envelope's documents and their page manifests", "tags": [ "Envelope documents", "EnvelopeDocument" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopeDocumentApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "put": { "operationId": "v1.envelopes.documents.update", "description": "Requires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Replace the draft's documents and pages. Each document is assembled from the given pages;\nfields follow their page, and fields on pages that are dropped are removed", "tags": [ "Envelope documents", "EnvelopeDocument" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`SetEnvelopeDocumentsApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SetEnvelopeDocumentsApiRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopeDocumentApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/pages": { "get": { "operationId": "v1.envelopes.pages.index", "description": "Requires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Every page of the envelope in order, numbered as fields number them", "tags": [ "Envelope documents", "EnvelopeDocument" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopePageApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/fields": { "get": { "operationId": "v1.envelopes.fields.index", "description": "Values are included, except signature and initials images.\n\nRequires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List an envelope's fields", "tags": [ "Envelope fields", "EnvelopeField" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FieldApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.envelopes.fields.store", "description": "Requires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Place a field. Coordinates are PDF points from the top-left of the displayed page; `page` is\nwithin `document` (which may be left out when the envelope has one document), and -1 is\nthe last page", "tags": [ "Envelope fields", "EnvelopeField" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`EnvelopeFieldApiRequestRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeFieldApiRequestRequest" } } } }, "responses": { "201": { "description": "`FieldApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FieldApiResponse" } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope. The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/fields\/{field}": { "get": { "operationId": "v1.envelopes.fields.show", "description": "Requires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a field", "tags": [ "Envelope fields", "EnvelopeField" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`FieldApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FieldApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.envelopes.fields.update", "description": "Changes only the attributes sent.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Update a field of a draft", "tags": [ "Envelope fields", "EnvelopeField" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`EnvelopeFieldApiRequestRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeFieldApiRequestRequest" } } } }, "responses": { "200": { "description": "`FieldApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FieldApiResponse" } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.envelopes.fields.destroy", "description": "Requires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Delete a field from a draft", "tags": [ "Envelope fields", "EnvelopeField" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "object": { "type": "string", "const": "field" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/form_fields": { "get": { "operationId": "v1.envelopes.form_fields.index", "description": "The fields the uploaded PDF's own form has, one entry per form field, with where each one is,\nits current value and who fills it. Envelopes made from a fillable PDF get them as fields;\nuntil a recipient is added nobody fills them, and the first signer added fills those still\nempty. Choose the ones recipients fill with `PUT \/envelopes\/{id}\/form_fields`, passing back\n`acceptance_digest`.\n\nRequires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List the PDF form's fields", "tags": [ "Envelope fields", "EnvelopeFormField" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EnvelopeFormFieldsApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeFormFieldsApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "put": { "operationId": "v1.envelopes.form_fields.update", "description": "`fields` lists the form fields recipients fill, each by `name` with the `recipient` (`rcp_\u2026`)\nwho fills it and optionally `required` and `label`. This replaces the current choice: every\nform field left out stays as it is in the PDF, with its current value, and nobody fills it.\nSignatures and initials can't stay empty: one left out keeps its current recipient, and the\ncall is refused if it has none. `acceptance_digest` must be the one the list returned; when\nthe form report needs acceptance (`requires_acceptance`), this call accepts it.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Choose and assign the PDF form's fields", "tags": [ "Envelope fields", "EnvelopeFormField" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`AssignFormFieldsApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AssignFormFieldsApiRequest" } } } }, "responses": { "200": { "description": "`EnvelopeFormFieldsApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeFormFieldsApiResponse" } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/recipients": { "get": { "operationId": "v1.envelopes.recipients.index", "description": "Requires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List an envelope's recipients", "tags": [ "Envelope recipients", "EnvelopeRecipient" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RecipientApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.envelopes.recipients.store", "description": "Requires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Add a recipient. Recipients with the same `routing_order` act at the same time; higher\nnumbers wait for every lower stage. `documents` limits which documents the recipient sees", "tags": [ "Envelope recipients", "EnvelopeRecipient" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`EnvelopeRecipientApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeRecipientApiRequest" } } } }, "responses": { "201": { "description": "`RecipientApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RecipientApiResponse" } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope. The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/recipients\/{recipient}": { "get": { "operationId": "v1.envelopes.recipients.show", "description": "Requires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a recipient", "tags": [ "Envelope recipients", "EnvelopeRecipient" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recipient", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`RecipientApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RecipientApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.envelopes.recipients.update", "description": "Changes only the attributes sent. Use corrections for a sent envelope.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Update a recipient of a draft", "tags": [ "Envelope recipients", "EnvelopeRecipient" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recipient", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`EnvelopeRecipientApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeRecipientApiRequest" } } } }, "responses": { "200": { "description": "`RecipientApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RecipientApiResponse" } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.envelopes.recipients.destroy", "description": "Their fields are removed with them.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Remove a recipient from a draft", "tags": [ "Envelope recipients", "EnvelopeRecipient" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recipient", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "object": { "type": "string", "const": "recipient" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelope_downloads\/{download}\/file": { "get": { "operationId": "v1.envelope_downloads.file", "summary": "Download an envelope ZIP using its expiring signed URL", "tags": [ "Envelope records", "SignedEnvelopeDownload" ], "parameters": [ { "name": "download", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "description": "The link is invalid or expired.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } }, "security": [] } }, "\/envelopes\/{envelope}\/archive": { "post": { "operationId": "v1.envelopes.archive", "description": "Hides a draft or finished envelope from lists (`archived: true`); restore brings it back.\nAn envelope out for signature must be voided first, and a legal hold blocks archiving: both\nare `409 resource_conflict`. Archiving an archived envelope changes nothing. An archived\ndraft is the same as a deleted one: it can be restored until the workspace's deleted-draft\nretention period ends, and is then purged.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Archive an envelope", "tags": [ "Envelope records", "EnvelopeRecord" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "The envelope is out for signature (void it first) or under a legal hold (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/restore": { "post": { "operationId": "v1.envelopes.restore", "description": "Restoring an envelope that isn't archived changes nothing.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Restore an archived envelope", "tags": [ "Envelope records", "EnvelopeRecord" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/legal_hold": { "post": { "operationId": "v1.envelopes.legal_hold", "description": "Holds the envelope (`legal_hold: true`): it can't be archived or deleted, and retention\nleaves it alone. Only an owner or admin can release a hold, in the app. Placing a hold on a\nheld envelope changes nothing.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Place a legal hold", "tags": [ "Envelope records", "EnvelopeRecord" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelope_downloads": { "post": { "operationId": "v1.envelope_downloads.store", "description": "`envelopes` lists up to 50 envelope IDs. The response links to one ZIP with each completed\nenvelope's signed PDF (all its documents in one file); `skipped` lists the others. The link\nneeds no API key and works for 10 minutes. Each envelope records the download in its audit\ntrail. If none is completed, the request fails with `422 validation_failed`.\n\nRequires the `artifacts:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Download completed envelopes as a ZIP", "tags": [ "Envelope records", "EnvelopeRecord" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateEnvelopeDownloadRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateEnvelopeDownloadRequest" } } } }, "responses": { "201": { "description": "The ZIP and its link.", "content": { "application\/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes": { "get": { "operationId": "v1.envelopes.index", "description": "The workspace's envelopes in the key's mode, newest first. `expand` adds `recipients`,\n`fields` or `documents` to each item. Archived envelopes are left out; `archived=true` lists\nonly them.\n\nRequires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List envelopes", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "type": "array", "default": [], "items": { "type": "string" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^env_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^env_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "filter[status]", "in": "query", "schema": { "anyOf": [ { "description": "Only envelopes in this status", "$ref": "#\/components\/schemas\/DocumentStatus" }, { "type": "null" } ] } }, { "name": "filter[external_id]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "Only envelopes with your own reference", "maxLength": 255 } }, { "name": "filter[template]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "Only envelopes made from this template (`tpl_\u2026`)", "pattern": "^tpl_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "filter[created]", "in": "query", "style": "deepObject", "schema": { "type": "object", "description": "Created within these bounds: `gte`, `lte` or both", "default": [], "properties": { "gte": { "type": "string", "format": "date-time" }, "lte": { "type": "string", "format": "date-time" } } }, "explode": true }, { "name": "filter[metadata]", "in": "query", "style": "deepObject", "schema": { "type": "object", "description": "Every given metadata key has this value", "default": [], "additionalProperties": { "type": "string" } }, "explode": true }, { "name": "filter[archived]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "`true` lists only archived envelopes", "enum": [ "true", "false", "1", "0" ] } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.envelopes.store", "description": "Builds a draft from ready files (`file`, or `documents` assembled from pages of ready files)\nuploaded with `POST \/files`. Nothing is sent until `POST \/envelopes\/{id}\/send`.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Create a draft envelope", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateEnvelopeRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateEnvelopeRequest" } } } }, "responses": { "201": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "The file is not ready, or host-managed notifications need `send_emails=false` (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}": { "get": { "operationId": "v1.envelopes.show", "description": "`expand` adds `recipients`, `fields` or `documents`. `status` is the envelope's lifecycle state and\n`finalization_status` tracks the signed PDF after the last signature. Archived envelopes can\nbe retrieved too (`archived: true`).\n\nRequires the `envelopes:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve an envelope", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "type": "array", "default": [], "items": { "type": "string" } } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.envelopes.update", "description": "Changes only the attributes sent: name, `external_id`, metadata, email subject and message,\nexpiry, `send_emails`, prefilled `values` and `notification_policy`. Recipients, fields and\ndocuments have their own endpoints. Only drafts can be changed (`409 resource_conflict`).\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Update a draft envelope", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`UpdateDraftEnvelopeRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateDraftEnvelopeRequest" } } } }, "responses": { "200": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "The envelope is no longer a draft, or host-managed notifications need `send_emails=false` (`resource_conflict`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.envelopes.destroy", "description": "Only drafts that were never sent can be deleted; void a sent envelope instead. An envelope\nunder legal hold is refused. The draft is archived (`archived: true`, see restore) and purged\nwhen the workspace's deleted-draft retention period ends.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Delete a draft envelope", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "409": { "description": "The envelope is no longer a draft (`resource_conflict`); use corrections for a sent envelope.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/send": { "post": { "operationId": "v1.envelopes.send", "description": "Issues signing links to the recipients whose turn it is and, unless `send_emails` is false,\nemails them. The draft needs at least one recipient who signs, approves or acknowledges.\nThe send counts toward the API allowance; a refused send is a `422 validation_failed` with\n`error.quota` (see Allowances). In a platform-owned workspace the send counts toward the\nplatform's plan, and a platform with no linked billing account can't send (`403`).\nHost-managed notifications need `send_emails=false` (`409 resource_conflict`).\n\nRequires the `envelopes:send` key ability. Platform keys must send `Workspace-Id`.", "summary": "Send a draft envelope", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "Host-managed notifications need `send_emails=false` (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/void": { "post": { "operationId": "v1.envelopes.void", "description": "Stops a sent envelope that is not fully signed: every signing link stops working.\nEveryone who was invited gets a short \"voided\" email with the `reason` (unless the\nenvelope's `voided` notification is host-managed). `reason` is optional, up to 1000\ncharacters, and is recorded in the audit log; without it a generic reason is used.\nThis cannot be undone.\n\nRequires the `envelopes:void` key ability. Platform keys must send `Workspace-Id`.", "summary": "Void a sent envelope", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`VoidEnvelopeRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/VoidEnvelopeRequest" } } } }, "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/remind": { "post": { "operationId": "v1.envelopes.remind", "description": "Emails a reminder to `recipient`, or without it to every recipient whose turn it is.\nA recipient who is not remindable (already acted, not their turn, reminders off or at their\nlimit, or host-managed notifications) is refused with `409 resource_conflict`; reminding the\nsame recipient again too soon is `429 rate_limit_exceeded`.\n\nRequires the `envelopes:send` key ability. Platform keys must send `Workspace-Id`.", "summary": "Remind recipients", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`RemindEnvelopeRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RemindEnvelopeRequest" } } } }, "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "Nobody can be reminded now: already signed, not their turn, reminders off, the reminder limit, or host-managed notifications (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/extend": { "post": { "operationId": "v1.envelopes.extend", "description": "Moves the expiry of a sent, not fully signed envelope `days` later. With\n`notify_pending_signers`, the recipients who have not acted are emailed the new deadline.\n\nRequires the `envelopes:send` key ability. Platform keys must send `Workspace-Id`.", "summary": "Extend an envelope's expiry", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`ExtendEnvelopeRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ExtendEnvelopeRequest" } } } }, "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "Notifying signers with host-managed notifications (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/duplicate": { "post": { "operationId": "v1.envelopes.duplicate", "description": "Copies any envelope's documents, recipients and fields into a new draft (`201`), optionally\nrenamed with `name`. Nothing is sent.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Duplicate an envelope", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`DuplicateEnvelopeRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/DuplicateEnvelopeRequest" } } } }, "responses": { "201": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "Host-managed notifications need `send_emails=false` (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/artifacts": { "get": { "operationId": "v1.envelopes.artifacts", "description": "Short-lived signed download links (5 minutes) for the original uploads, the signing PDF, the\nfinalized or sealed PDF, per-document sealed copies, the certificate and the evidence\npackage, as far as each exists yet. Links are null until the file exists.\n\nRequires the `artifacts:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List an envelope's files", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EnvelopeArtifactsApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeArtifactsApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/retry-finalization": { "post": { "operationId": "v1.envelopes.retryFinalization", "description": "Requeues the signed PDF of an envelope that every recipient has acted on but whose\n`finalization_status` is `failed`. Any other envelope is refused (`422 validation_failed`).\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retry finalization", "tags": [ "EnvelopeLifecycle" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/events": { "get": { "operationId": "v1.events.index", "description": "Every domain event of the last 30 days, newest first, whether or not an endpoint was\nsubscribed. Filter with `filter[type]`, `filter[object]` (the object's ID) and\n`filter[created][gt|gte|lt|lte]` (ISO 8601 or Unix timestamp).\n\nRequires the `webhooks:read` key ability.", "summary": "List events", "tags": [ "Events", "Event" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "filter[type]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "Only this event type, for example `envelope.completed`", "maxLength": 64 } }, { "name": "filter[object]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "Only events about this object (an envelope, recipient or template ID)", "maxLength": 64 } }, { "name": "filter[created]", "in": "query", "style": "deepObject", "schema": { "type": "object", "description": "Created within these bounds (`gt`, `gte`, `lt`, `lte`): an ISO 8601 date or a Unix timestamp", "default": [], "properties": { "gt": { "type": "string", "maxLength": 64 }, "gte": { "type": "string", "maxLength": 64 }, "lt": { "type": "string", "maxLength": 64 }, "lte": { "type": "string", "maxLength": 64 } } }, "explode": true }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EventApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/events\/{event}": { "get": { "operationId": "v1.events.show", "description": "Requires the `webhooks:read` key ability.", "summary": "Retrieve an event", "tags": [ "Events", "Event" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`EventApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EventApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/events\/{event}\/resend": { "post": { "operationId": "v1.events.resend", "description": "Creates a new delivery of the event to one endpoint, with a fresh signature.\n\nRequires the `webhooks:write` key ability.", "summary": "Resend an event", "tags": [ "Events", "Event" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "webhook_endpoint": { "type": "string" } }, "required": [ "webhook_endpoint" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookDeliveryApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/files": { "post": { "operationId": "v1.files.store", "description": "Send `multipart\/form-data` with `file` (up to 25 MB by default), or JSON with the HTTPS `url` of a PDF\nto fetch. `file` can be a PDF; a Word, Excel, PowerPoint, OpenDocument, RTF or plain-text file (`doc`, `docx`,\n`odt`, `rtf`, `txt`, `xls`, `xlsx`, `ods`, `ppt`, `pptx`, `odp`); or an image (`jpg`, `jpeg`, `png`, `gif`,\n`webp`, `tif`, `tiff`, `bmp`, `heic`, `heif`). Office files and images are converted to PDF; each image becomes\none Letter page, turned upright by its Exif orientation, and a multi-page TIFF becomes one page per image (up to\n50). `password` unlocks a protected PDF and\n`use_text_tags` places fields from text tags. A fillable PDF's own form fields are found and\nset up as fields unless `import_form_fields` is `false`; list and assign them with\n`GET` and `PUT \/envelopes\/{id}\/form_fields`. Use the returned `file_\u2026` ID in\n`POST \/envelopes` or `POST \/templates` once its `status` is `ready`. Emits `file.ready` or\n`file.failed`.\n\nRequires the `files:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Upload a file", "tags": [ "Files", "File" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateFileRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateFileRequest" } } } }, "responses": { "201": { "description": "`FileApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FileApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/files\/{file}": { "get": { "operationId": "v1.files.show", "description": "Poll `status` until it is `ready` or `failed`.\n\nRequires the `files:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a file", "tags": [ "Files", "File" ], "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`FileApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FileApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/envelopes\/{envelope}\/filing_rule": { "post": { "operationId": "v1.envelopes.filing_rule", "description": "`filing_rule` is a filing rule (`frl_\u2026`), or `null` to clear it. The rule files the envelope\ninto its folders as its status changes, even if it was moved by hand before. Needs the\nfiling rules plan feature.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Assign a filing rule to an envelope", "tags": [ "Filing rules", "FilingRuleAssignment" ], "parameters": [ { "name": "envelope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`AssignFilingRuleApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AssignFilingRuleApiRequest" } } } }, "responses": { "200": { "description": "An assignment changes the envelope, it does not create one: 200, not the POST default of 201.\n\n\n\n`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/filing_rule": { "post": { "operationId": "v1.templates.filing_rule", "description": "`filing_rule` is a filing rule (`frl_\u2026`), or `null` to clear it. Envelopes created from the\ntemplate are filed by it. Needs the filing rules plan feature.\n\nRequires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Assign a filing rule to a template", "tags": [ "Filing rules", "FilingRuleAssignment" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`AssignFilingRuleApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AssignFilingRuleApiRequest" } } } }, "responses": { "200": { "description": "`TemplateApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/filing_rules": { "get": { "operationId": "v1.filing_rules.index", "description": "The workspace's filing rules, newest first. A rule maps envelope statuses (`sent`, `completed`,\n`voided`, `declined`, `expired`) to envelope folders; an envelope using the rule moves there when\nit reaches the status, unless someone moved it by hand. Needs a plan with filing rules\n(`403 permission_denied` otherwise).\n\nRequires the `folders:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List filing rules", "tags": [ "Filing rules", "FilingRule" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FilingRuleApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.filing_rules.store", "description": "Names are unique in the workspace. `targets` has at most one envelope folder per status.\n`is_default: true` makes it the rule new envelopes start with in the app, replacing the\nprevious default.\n\nRequires the `folders:write` key ability. Platform keys must send `Workspace-Id`. Live keys only: a test key gets `403 live_key_required`.", "summary": "Create a filing rule", "tags": [ "Filing rules", "FilingRule" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateFilingRuleApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateFilingRuleApiRequest" } } } }, "responses": { "201": { "description": "`FilingRuleApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FilingRuleApiResponse" } } } }, "409": { "description": "The workspace has no member to own it (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/filing_rules\/{filingRule}": { "get": { "operationId": "v1.filing_rules.show", "description": "Requires the `folders:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a filing rule", "tags": [ "Filing rules", "FilingRule" ], "parameters": [ { "name": "filingRule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`FilingRuleApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FilingRuleApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.filing_rules.update", "description": "Changes only what is sent. `targets` replaces every destination. `is_default: false` on the\ndefault rule leaves the workspace without one. Envelopes already filed are not moved again.\n\nRequires the `folders:write` key ability. Platform keys must send `Workspace-Id`. Live keys only: a test key gets `403 live_key_required`.", "summary": "Update a filing rule", "tags": [ "Filing rules", "FilingRule" ], "parameters": [ { "name": "filingRule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`UpdateFilingRuleApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateFilingRuleApiRequest" } } } }, "responses": { "200": { "description": "`FilingRuleApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FilingRuleApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.filing_rules.destroy", "description": "Envelopes using it stay where they are and are no longer filed.\n\nRequires the `folders:write` key ability. Platform keys must send `Workspace-Id`. Live keys only: a test key gets `403 live_key_required`.", "summary": "Delete a filing rule", "tags": [ "Filing rules", "FilingRule" ], "parameters": [ { "name": "filingRule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "filing_rule" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/folders": { "get": { "operationId": "v1.folders.index", "description": "The workspace's envelope and template folders, newest first. Folders are shared by test and\nlive keys, as in the app. `type` keeps one kind; `parent` keeps the folders directly inside\none folder. Rebuild the tree from each folder's `parent`.\n\nRequires the `folders:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List folders", "tags": [ "Folders", "Folder" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "filter[type]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "Only `envelope` or only `template` folders", "enum": [ "envelope", "template" ] } }, { "name": "filter[parent]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "Only the folders directly inside this folder (`fdr_\u2026`)", "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FolderApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.folders.store", "description": "`type` is `envelope` (default) or `template`. Pass `parent` to nest it in a folder of the same\ntype. Names are unique among a folder's direct subfolders.\n\nRequires the `folders:write` key ability. Platform keys must send `Workspace-Id`. Live keys only: a test key gets `403 live_key_required`.", "summary": "Create a folder", "tags": [ "Folders", "Folder" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateFolderApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateFolderApiRequest" } } } }, "responses": { "201": { "description": "`FolderApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FolderApiResponse" } } } }, "409": { "description": "The workspace has no member to own it (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/folders\/{folder}": { "get": { "operationId": "v1.folders.show", "description": "Requires the `folders:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a folder", "tags": [ "Folders", "Folder" ], "parameters": [ { "name": "folder", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`FolderApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FolderApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.folders.update", "description": "Rename it, set `use_for_visitor_check_in` (envelope folders only), or move it with `parent`: a\nfolder of the same type, or `null` for the top level. A folder cannot move into itself or one\nof its subfolders. Its contents move with it.\n\nRequires the `folders:write` key ability. Platform keys must send `Workspace-Id`. Live keys only: a test key gets `403 live_key_required`.", "summary": "Update a folder", "tags": [ "Folders", "Folder" ], "parameters": [ { "name": "folder", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`UpdateFolderApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateFolderApiRequest" } } } }, "responses": { "200": { "description": "`FolderApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FolderApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.folders.destroy", "description": "A folder does not need to be empty, as in the app: its subfolders, envelopes and templates move\nup to its parent (the top level when it has none), and any filing rule destination that pointed\nat it is cleared, so envelopes reaching that status are no longer filed.\n\nRequires the `folders:write` key ability. Platform keys must send `Workspace-Id`. Live keys only: a test key gets `403 live_key_required`.", "summary": "Delete a folder", "tags": [ "Folders", "Folder" ], "parameters": [ { "name": "folder", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "folder" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/identity_providers": { "get": { "operationId": "v1.identity_providers.index", "description": "Requires the `identity_providers:write` key ability. Live keys only: a test key gets `403 live_key_required`.", "summary": "List this platform's provider. Requires a platform key with identity_providers:write. Secrets and pinned signing keys are never returned", "tags": [ "Identity providers", "IdentityProvider" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/IdentityProviderApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.identity_providers.store", "description": "Requires the `identity_providers:write` key ability. Live keys only: a test key gets `403 live_key_required`.", "summary": "Register the platform's one OIDC provider using SSRF-safe discovery. Requires client_secret on creation", "tags": [ "Identity providers", "IdentityProvider" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`SaveIdentityProviderRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveIdentityProviderRequest" } } } }, "responses": { "201": { "description": "`IdentityProviderApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/IdentityProviderApiResponse" } } } }, "409": { "description": "The platform already has an identity provider; update it instead (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/identity_providers\/{idp}": { "get": { "operationId": "v1.identity_providers.show", "description": "Secrets and pinned signing keys are never returned.\n\nRequires the `identity_providers:write` key ability. Live keys only: a test key gets `403 live_key_required`.", "summary": "Retrieve the identity provider", "tags": [ "Identity providers", "IdentityProvider" ], "parameters": [ { "name": "idp", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`IdentityProviderApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/IdentityProviderApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.identity_providers.update", "description": "Requires the `identity_providers:write` key ability. Live keys only: a test key gets `403 live_key_required`.", "summary": "Replace provider settings, preserving its secret and console MFA arrays when omitted. Re-enables a disabled provider", "tags": [ "Identity providers", "IdentityProvider" ], "parameters": [ { "name": "idp", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`SaveIdentityProviderRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveIdentityProviderRequest" } } } }, "responses": { "200": { "description": "`IdentityProviderApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/IdentityProviderApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.identity_providers.destroy", "description": "Requires the `identity_providers:write` key ability. Live keys only: a test key gets `403 live_key_required`.", "summary": "Disable the provider, matching the console. Existing registration remains available for audit and subsequent updates", "tags": [ "Identity providers", "IdentityProvider" ], "parameters": [ { "name": "idp", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/identity_providers\/{idp}\/subjects\/{sub}\/deprovision": { "post": { "operationId": "v1.identity_providers.subjects.deprovision", "description": "Requires the `identity_providers:write` key ability.", "summary": "End a subject's platform sessions and remove only memberships managed by this IdP", "tags": [ "Identity providers", "DeprovisionIdentity" ], "parameters": [ { "name": "idp", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sub", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "deprovision_result" }, "identity_provider": { "type": "string" }, "subject": { "type": "string" }, "memberships_removed": { "type": "integer" } }, "required": [ "object", "identity_provider", "subject", "memberships_removed" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/login_links": { "post": { "operationId": "v1.login_links.store", "description": "Platform keys only. Returns a single-use URL (valid for 60 seconds) that signs the\nperson in to one of the platform's workspaces. The person is identified by\n`(platform, actor.external_id)`, and is given the workspace role in `actor.role`\n(`admin` or `member`, never `owner`). Set `actor.email_verified: true` only if the\nplatform has verified the address: otherwise the person is provisioned without\nrecipient-portal linking, and an existing eSignStack account with the same email is\nnever merged. A first sign-in whose email matches an existing account first asks the\naccount holder to confirm by email.\n\nRequires the `login_links:write` key ability.", "summary": "Create a login link", "tags": [ "Login links", "LoginLink" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "string", "maxLength": 64 }, "return_to": { "type": [ "string", "null" ], "maxLength": 2048 }, "actor": { "type": "object", "properties": { "external_id": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "role": { "type": "string", "maxLength": 32 }, "email_verified": { "type": [ "boolean", "null" ] } }, "required": [ "external_id", "email", "role" ] } }, "required": [ "workspace", "actor" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/LoginLinkApiResponse" } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/login_identities\/{externalId}\/deprovision": { "post": { "operationId": "v1.login_identities.deprovision", "description": "Removes every membership that login links created for `external_id` and ends their\nplatform sessions at once. Their eSignStack account, standalone workspaces and the\nworkspaces' documents are untouched. A later login link signs them in again.\n\nRequires the `login_links:write` key ability.", "summary": "Deprovision a person", "tags": [ "Login links", "LoginLink" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "deprovision_result" }, "external_id": { "type": "string" }, "memberships_removed": { "type": "integer" } }, "required": [ "object", "external_id", "memberships_removed" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/platform": { "get": { "operationId": "v1.platform.show", "description": "The calling platform key's platform and its console settings. Settings change only in the\nplatform console.\n\nRequires the `platform:read` key ability.", "summary": "Retrieve the platform", "tags": [ "Platform" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PlatformApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PlatformApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/platform\/members": { "get": { "operationId": "v1.platform.members.index", "description": "Everyone with access to the platform console, by name, with their role. Filter with\n`filter[role]` (`admin`, `developer`, `support` or `billing`). The list is one page.\nInviting people and changing roles happen only in the console.\n\nRequires the `platform:read` key ability.", "summary": "List platform members", "tags": [ "Platform" ], "parameters": [ { "name": "filter[role]", "in": "query", "schema": { "anyOf": [ { "description": "Only members with this role", "$ref": "#\/components\/schemas\/PlatformRole" }, { "type": "null" } ] } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PlatformMemberApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/verify": { "post": { "operationId": "v1.verify", "description": "Send exactly one of pdf (multipart upload, at most 20 MiB) or sha256.\nUploads use the public page's bounded, temporary verification pipeline.\nHash lookup does not validate signatures, timestamps, or possession of the PDF.", "summary": "Verify a PDF or look up its SHA-256 hash. No API key is required", "tags": [ "Public verification", "PublicVerification" ], "requestBody": { "description": "`VerifyPublicDocumentRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/VerifyPublicDocumentRequest" } } } }, "responses": { "200": { "description": "`PublicVerificationResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PublicVerificationResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/artifacts\/{artifact}\/download": { "get": { "operationId": "v1.artifacts.download", "summary": "Download an immutable artifact using its expiring signed URL", "tags": [ "SignedArtifactDownload" ], "parameters": [ { "name": "artifact", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Immutable artifact bytes. Content-Type is the stored artifact MIME type; PDFs use application\/pdf.", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } }, "*\/*": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } }, "security": [] } }, "\/envelopes\/{env}\/recipients\/{rcp}\/signing_sessions": { "post": { "operationId": "v1.envelopes.recipients.signing_sessions.store", "description": "Platform keys require Workspace-Id. The envelope must be in the key's mode: a test key\ncannot open a session on a live envelope. Opening the URL still requires the\nrecipient's configured signer authentication. Return URLs are UX signals,\nnot proof of signing; confirm outcomes through the API or webhooks.\n\nAn envelope sent from the app (or by a signer) starts counting as API usage the first\ntime the API issues it a session, so this call can be refused with a 422 allowance\nerror (`error.quota.code`) like a send.\n\nRequires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Create a single-use hosted or embedded signing URL", "tags": [ "Signing sessions", "SigningSession" ], "parameters": [ { "name": "env", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rcp", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateSigningSessionApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateSigningSessionApiRequest" } } } }, "responses": { "201": { "description": "`SigningSessionApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SigningSessionApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/documents": { "get": { "operationId": "v1.templates.documents.index", "description": "Requires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "The template's documents and their page manifests", "tags": [ "Template documents", "TemplateDocument" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateDocumentApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "put": { "operationId": "v1.templates.documents.update", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Replace the template's documents and pages. Each document is assembled from pages of ready\nuploaded files (`file`) or of the template's current documents (`document`); `visible_to`\nnames the roles that see it. Fields follow their page; fields on dropped pages are removed", "tags": [ "Template documents", "TemplateDocument" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`SetTemplateDocumentsApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SetTemplateDocumentsApiRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateDocumentApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/pages": { "get": { "operationId": "v1.templates.pages.index", "description": "Requires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Every page of the template in order, numbered as fields number them", "tags": [ "Template documents", "TemplateDocument" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplatePageApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/fields": { "get": { "operationId": "v1.templates.fields.index", "description": "Requires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List a template's fields", "tags": [ "Template fields", "TemplateField" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateFieldApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.templates.fields.store", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Place a field. Coordinates are PDF points from the top-left of the displayed page; `page` is\nwithin `document` (which may be left out when the template has one document), and -1 is the\nlast page. A field belongs to a signer `role`, or is a `prefill` field", "tags": [ "Template fields", "TemplateField" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`TemplateFieldApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateFieldApiRequest" } } } }, "responses": { "201": { "description": "`TemplateFieldApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateFieldApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/fields\/{field}": { "get": { "operationId": "v1.templates.fields.show", "description": "Requires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a template field", "tags": [ "Template fields", "TemplateField" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`TemplateFieldApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateFieldApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.templates.fields.update", "description": "Changes only the attributes sent.\n\nRequires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Update a template field", "tags": [ "Template fields", "TemplateField" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`TemplateFieldApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateFieldApiRequest" } } } }, "responses": { "200": { "description": "`TemplateFieldApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateFieldApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.templates.fields.destroy", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Delete a template field", "tags": [ "Template fields", "TemplateField" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "object": { "type": "string", "const": "template_field" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/form_fields": { "get": { "operationId": "v1.templates.form_fields.index", "description": "The fields the template's PDF form has, one entry per form field, with where each one is,\nits default value and the role that fills it. Choose the ones roles fill with\n`PUT \/templates\/{id}\/form_fields`, passing back `acceptance_digest`.\n\nRequires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "List the PDF form's fields", "tags": [ "Template fields", "TemplateFormField" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`TemplateFormFieldsApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateFormFieldsApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "put": { "operationId": "v1.templates.form_fields.update", "description": "`fields` lists the form fields roles fill, each by `name` with the `role` that fills it and\noptionally `required` and `label`. This replaces the current choice: every form field left\nout stays as it is in the PDF, with its default value, and nobody fills it. Signatures and\ninitials can't stay empty: one left out keeps its current role, and the call is refused if\nit has none. `acceptance_digest` must be the one the list returned.\n\nRequires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Choose and assign the PDF form's fields", "tags": [ "Template fields", "TemplateFormField" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`AssignTemplateFormFieldsApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AssignTemplateFormFieldsApiRequest" } } } }, "responses": { "200": { "description": "`TemplateFormFieldsApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateFormFieldsApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/roles": { "get": { "operationId": "v1.templates.roles.index", "description": "Requires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "The template's roles in order. Each becomes a recipient of an envelope made from the template", "tags": [ "Template roles", "TemplateRole" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateRoleApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "put": { "operationId": "v1.templates.roles.update", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Replace the template's roles. `type` is `signer`, `approver`, `viewer` or `cc`; roles with\nequal `routing_order` act in parallel. A role that has fields must stay a signer role", "tags": [ "Template roles", "TemplateRole" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`SetTemplateRolesApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SetTemplateRolesApiRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateRoleApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/move": { "post": { "operationId": "v1.templates.move", "description": "`folder` is a template folder (`fdr_\u2026`), or `null` to take it out of its folder.\n\nRequires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Move a template to a folder", "tags": [ "Templates", "TemplateFolder" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`MoveToFolderApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MoveToFolderApiRequest" } } } }, "responses": { "200": { "description": "`TemplateApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates": { "get": { "operationId": "v1.templates.index", "description": "Requires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "The workspace's templates in the key's mode, newest first", "tags": [ "Templates", "Template" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "type": "array", "default": [], "items": { "type": "string" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^tpl_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^tpl_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "filter[created]", "in": "query", "style": "deepObject", "schema": { "type": "object", "description": "Created within these bounds: `gte`, `lte` or both", "default": [], "properties": { "gte": { "type": "string", "format": "date-time" }, "lte": { "type": "string", "format": "date-time" } } }, "explode": true }, { "name": "filter[metadata]", "in": "query", "style": "deepObject", "schema": { "type": "object", "description": "Every given metadata key has this value", "default": [], "additionalProperties": { "type": "string" } }, "explode": true }, { "name": "filter[archived]", "in": "query", "schema": { "type": [ "string", "null" ], "description": "`true` lists only archived templates", "enum": [ "true", "false", "1", "0" ] } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.templates.store", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Create a template from uploaded files (`documents`, each assembled from pages of ready files)\nor save an envelope as a template (`envelope`, which also needs `envelopes:read`). The template\ntakes the key's mode. Place fields afterwards with the template field endpoints", "tags": [ "Templates", "Template" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateTemplateApiRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateTemplateApiRequest" } } } }, "responses": { "201": { "description": "`TemplateApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } } } }, "409": { "description": "The workspace has no member to own it (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}": { "get": { "operationId": "v1.templates.show", "description": "`expand` adds `documents`, `roles` or `fields`. Archived templates can be retrieved too\n(`archived: true`).\n\nRequires the `templates:read` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve a template", "tags": [ "Templates", "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "type": "array", "default": [], "items": { "type": "string" } } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`TemplateApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.templates.update", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Change the template's name, metadata, default return URL or notification policy. Envelopes\nalready made from the template are not changed", "tags": [ "Templates", "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`UpdateTemplateApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateTemplateApiRequest" } } } }, "responses": { "200": { "description": "`TemplateApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.templates.destroy", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Archive the template. Envelopes already made from it are unaffected", "tags": [ "Templates", "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/preview": { "post": { "operationId": "v1.templates.preview", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Render a watermarked preview of the template, with each field drawn as a label showing its type\nand role, behind a short-lived (15 minute) link. Nothing is sent. Editing the template makes\na new version; preview again to see the change", "tags": [ "Templates", "TemplateAction" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "A new preview, as POST \/envelopes\/{id}\/preview: 201.\n\n\n\n`TemplatePreviewApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplatePreviewApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/duplicate": { "post": { "operationId": "v1.templates.duplicate", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Duplicate the template: its documents, roles, fields and settings. The copy is named \"\u2026 (copy)\",\nstarts at version 1 and has its share link and Kiosk mode off", "tags": [ "Templates", "TemplateAction" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "`TemplateApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } } } }, "409": { "description": "The workspace has no member to own it (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/restore": { "post": { "operationId": "v1.templates.restore", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Restore an archived template (one deleted with `DELETE \/templates\/{id}`). Restoring an active\ntemplate changes nothing", "tags": [ "Templates", "TemplateAction" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`TemplateApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/share_link": { "post": { "operationId": "v1.templates.share_link.store", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Turn on the template's public share link and return its URL. Anyone with the URL can sign as\n`role`, and each visit creates a new envelope from the template. The template needs one signer\nrole and no prefilled fields. Turning it on again keeps the same URL", "tags": [ "Templates", "TemplateAction" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`EnableTemplateShareLinkApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnableTemplateShareLinkApiRequest" } } } }, "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`TemplateShareLinkApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateShareLinkApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.templates.share_link.destroy", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Turn off the share link. Its URL stops working; turning it on later gives a new URL", "tags": [ "Templates", "TemplateAction" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`TemplateShareLinkApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateShareLinkApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/kiosk": { "post": { "operationId": "v1.templates.kiosk.store", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Turn on Kiosk mode and return the kiosk URL to open on the shared device. Each visitor signs as\n`role` in a new envelope. The template needs one signer role, no prefilled fields, and no SMS\nverification on that role", "tags": [ "Templates", "TemplateAction" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`EnableTemplateKioskApiRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnableTemplateKioskApiRequest" } } } }, "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`TemplateKioskApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateKioskApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.templates.kiosk.destroy", "description": "Requires the `templates:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Turn off Kiosk mode. The kiosk URL stops working and the staff PIN is cleared", "tags": [ "Templates", "TemplateAction" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`TemplateKioskApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateKioskApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/templates\/{template}\/envelopes": { "post": { "operationId": "v1.templates.envelopes.store", "description": "Requires the `envelopes:write` key ability. Platform keys must send `Workspace-Id`.", "summary": "Create an envelope from the template. Map each role to a recipient by `role_label`. Roles\nwithout fields may be left out; a role with fields must be mapped when `send` is true, while\na draft keeps a blank recipient for it to fill in later. With `send: true` the envelope is\nsent at once and counts toward the API allowance (see Allowances). Test keys get a\nwatermarked test envelope", "tags": [ "Templates", "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`CreateEnvelopeFromTemplateRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateEnvelopeFromTemplateRequest" } } } }, "responses": { "201": { "description": "`EnvelopeApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EnvelopeApiResponse" } } } }, "409": { "description": "Host-managed notifications need `send_emails=false` (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/usage": { "get": { "operationId": "v1.usage.index", "description": "One item per workspace for `period` (`YYYY-MM`, default the current month): a workspace key\ngets its own workspace, a platform key without `Workspace-Id` every workspace it owns in the\nkey's mode, or one with `workspace`. `metrics` counts `envelope.sent`, `envelope.completed`,\n`email.sent`, `sms.sent`, `seal.created` and `timestamp.requested`, plus the latest\n`storage.bytes`.\n\nEach item also has `api_envelopes`: the billing account's API and MCP allowance in its\ncurrent window (`used`, `limit`, `remaining`, `overage`, `resets_at`), whatever `period` is\nrequested. It's null for platform-managed workspaces, whose API sends count toward the\nplatform's own Platform plan. On Platform plans it also has `spending_cap` for the extra\nenvelopes past the allowance (each billed at the plan's per-envelope rate): `cap_cents`\n(null for no limit), `used_cents`, `remaining_cents` and `resets_at` (the end of the metered\nusage month, which can differ from the allowance window). Past the cap, API sends beyond the\nallowance are refused with `api_spending_cap_reached`.\n\nA platform key without `Workspace-Id` also gets `platform`: the platform's own Platform plan\nallowance, which its workspaces' API sends count toward. Its `api_envelopes` has the same\nshape (used, limit, remaining, overage, resets_at and spending_cap), and is null when the\nplatform has no billing account linked. `platform` is null for every other key.\n\nRequires the `usage:read` key ability.", "summary": "List monthly usage counters per workspace", "tags": [ "Usage" ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "workspace", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^ws_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WorkspaceUsageApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" }, "platform": { "anyOf": [ { "$ref": "#\/components\/schemas\/PlatformUsageApiResponse" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "url", "platform" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/webhook_endpoints": { "get": { "operationId": "v1.webhook_endpoints.index", "description": "Requires the `webhooks:read` key ability.", "summary": "List webhook endpoints", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookEndpointApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.webhook_endpoints.store", "description": "The URL must be HTTPS. The signing secret is returned in this response only.\nWorkspace keys create workspace endpoints; a platform key without\n`Workspace-Id` creates a platform endpoint that receives all of the\nplatform's workspaces' events.\n\nRequires the `webhooks:write` key ability.", "summary": "Create a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 20 }, "enabled_events": { "type": "array", "items": { "type": "string", "enum": [ "envelope.created", "envelope.sent", "envelope.corrected", "envelope.completed", "envelope.voided", "envelope.declined", "envelope.expired", "envelope.expiration_extended", "envelope.finalization_failed", "recipient.activated", "recipient.delivery_sent", "recipient.delivery_bounced", "recipient.viewed", "recipient.consented", "recipient.authentication_failed", "recipient.authentication_locked", "recipient.signed", "recipient.approved", "recipient.acknowledged", "recipient.declined", "recipient.reassigned", "reminder.sent", "file.ready", "file.failed", "template.created", "template.updated", "template.deleted", "workspace.created", "workspace.updated", "workspace.suspended", "workspace.member_provisioned", "workspace.member_deprovisioned", "webhook_endpoint.disabled", "*" ] }, "minItems": 1 }, "include": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "field_values" ] } } }, "required": [ "url", "enabled_events" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookEndpointApiResponse" } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/webhook_endpoints\/{endpoint}": { "get": { "operationId": "v1.webhook_endpoints.show", "description": "Requires the `webhooks:read` key ability.", "summary": "Retrieve a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookEndpointApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookEndpointApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.webhook_endpoints.update", "description": "URL, events, description, metadata and `status` (`enabled` or `disabled`) can change in place.\n\nRequires the `webhooks:write` key ability.", "summary": "Update a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 20 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "enabled_events": { "type": "array", "items": { "type": "string", "enum": [ "envelope.created", "envelope.sent", "envelope.corrected", "envelope.completed", "envelope.voided", "envelope.declined", "envelope.expired", "envelope.expiration_extended", "envelope.finalization_failed", "recipient.activated", "recipient.delivery_sent", "recipient.delivery_bounced", "recipient.viewed", "recipient.consented", "recipient.authentication_failed", "recipient.authentication_locked", "recipient.signed", "recipient.approved", "recipient.acknowledged", "recipient.declined", "recipient.reassigned", "reminder.sent", "file.ready", "file.failed", "template.created", "template.updated", "template.deleted", "workspace.created", "workspace.updated", "workspace.suspended", "workspace.member_provisioned", "workspace.member_deprovisioned", "webhook_endpoint.disabled", "*" ] }, "minItems": 1 }, "include": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "field_values" ] } } } } } } }, "responses": { "200": { "description": "`WebhookEndpointApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookEndpointApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "delete": { "operationId": "v1.webhook_endpoints.destroy", "description": "Soft-deletes it; delivery history stays for 30 days.\n\nRequires the `webhooks:write` key ability.", "summary": "Delete a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/webhook_endpoints\/{endpoint}\/deliveries": { "get": { "operationId": "v1.webhook_endpoints.deliveries", "description": "Newest first, including failed (dead-lettered) ones with their last response.\nFilter with `filter[status]`.\n\nRequires the `webhooks:read` key ability.", "summary": "List deliveries of an endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "pending", "retrying", "delivered", "failed" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookDeliveryApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/webhook_endpoints\/{endpoint}\/deliveries\/{delivery}": { "get": { "operationId": "v1.webhook_endpoints.delivery", "description": "Requires the `webhooks:read` key ability.", "summary": "Retrieve a delivery with its attempts", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookDeliveryApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookDeliveryApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/webhook_endpoints\/{endpoint}\/rotate_secret": { "post": { "operationId": "v1.webhook_endpoints.rotate_secret", "description": "`expire_old_in` (0 to 86400 seconds) keeps the old secret signing too, so\ndeliveries carry two `v1=` signatures during the overlap.\n\nRequires the `webhooks:write` key ability.", "summary": "Rotate the signing secret", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "expire_old_in": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 86400 } } } } } }, "responses": { "200": { "description": "Data responses default to 201 on POST; this action returns the updated resource.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookEndpointApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/webhook_endpoints\/{endpoint}\/test": { "post": { "operationId": "v1.webhook_endpoints.test", "description": "Queues a real, signed delivery of a sample payload.\n\nRequires the `webhooks:write` key ability.", "summary": "Send a test event", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "envelope.created", "envelope.sent", "envelope.corrected", "envelope.completed", "envelope.voided", "envelope.declined", "envelope.expired", "envelope.expiration_extended", "envelope.finalization_failed", "recipient.activated", "recipient.delivery_sent", "recipient.delivery_bounced", "recipient.viewed", "recipient.consented", "recipient.authentication_failed", "recipient.authentication_locked", "recipient.signed", "recipient.approved", "recipient.acknowledged", "recipient.declined", "recipient.reassigned", "reminder.sent", "file.ready", "file.failed", "template.created", "template.updated", "template.deleted", "workspace.created", "workspace.updated", "workspace.suspended", "workspace.member_provisioned", "workspace.member_deprovisioned", "webhook_endpoint.disabled" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookDeliveryApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/webhook_endpoints\/{endpoint}\/resend_failed": { "post": { "operationId": "v1.webhook_endpoints.resend_failed", "description": "Creates new deliveries for the endpoint's dead-lettered ones created in an optional time range.\n\nRequires the `webhooks:write` key ability.", "summary": "Resend failed deliveries", "tags": [ "Webhook endpoints", "WebhookEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "created": { "type": "object", "properties": { "gte": { "type": [ "string", "null" ], "format": "date-time" }, "lte": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "resend_result" }, "resent": { "type": "integer" } }, "required": [ "object", "resent" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/workspaces\/{workspace}\/export": { "get": { "operationId": "v1.workspaces.exports.store", "description": "Requires the `workspaces:export` key ability. Platform keys must send `Workspace-Id`.", "summary": "Request a queued, audited export. This GET creates a job; do not prefetch it", "tags": [ "Workspace exports", "WorkspaceExport" ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "`WorkspaceExportApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceExportApiResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Location": { "schema": { "type": "string" } } } }, "409": { "description": "A workspace export is already running (`export_in_progress`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/workspaces\/{workspace}\/exports\/{export}": { "get": { "operationId": "v1.workspaces.exports.show", "description": "Poll until `status` is `ready`; the response then carries a signed download URL.\n\nRequires the `workspaces:export` key ability. Platform keys must send `Workspace-Id`.", "summary": "Retrieve an export", "tags": [ "Workspace exports", "WorkspaceExport" ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "export", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WorkspaceExportApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceExportApiResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/workspaces\/{workspace}\/exports\/{export}\/download": { "get": { "operationId": "v1.workspaces.exports.download", "description": "Requires the `workspaces:export` key ability. Platform keys must send `Workspace-Id`.", "summary": "Download the ready ZIP once, using its signed URL and the requesting API key", "tags": [ "Workspace exports", "WorkspaceExport" ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "export", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Required for this operation with a platform key.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Private ZIP download. Requires the requesting export-capable key and an unexpired single-use signed URL.", "content": { "application\/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "400": { "description": "A platform key sent no `Workspace-Id` (`workspace_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/workspaces": { "get": { "operationId": "v1.workspaces.index", "description": "The workspaces this platform owns, in the key's mode.\n\nRequires the `workspaces:read` key ability.", "summary": "List workspaces", "tags": [ "Workspaces", "Workspace" ], "parameters": [ { "name": "filter[external_id]", "in": "query", "schema": { "type": "string" } }, { "name": "filter[name]", "in": "query", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "ending_before", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WorkspaceApiResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "object", "data", "has_more", "url" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "post": { "operationId": "v1.workspaces.store", "description": "Provisions a customer workspace owned by the platform, in the key's mode. Responds `201` with\nthe new workspace, or `200` with the existing one when the platform already has a workspace\nwith this `external_id`.\n\nRequires the `workspaces:write` key ability.", "summary": "Create a workspace", "tags": [ "Workspaces", "Workspace" ], "parameters": [ { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "requestBody": { "description": "`WorkspaceRequest`", "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceRequest" } } } }, "responses": { "200": { "description": "The existing workspace with this `external_id`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceApiResponse" } } } }, "201": { "description": "The new workspace.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceApiResponse" } } } }, "409": { "description": "This `external_id` already belongs to a workspace with different creation attributes (`resource_conflict`). The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/workspaces\/{workspace}": { "get": { "operationId": "v1.workspaces.show", "description": "Requires the `workspaces:read` key ability.", "summary": "Retrieve a workspace", "tags": [ "Workspaces", "Workspace" ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WorkspaceApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } }, "patch": { "operationId": "v1.workspaces.update", "description": "Changes only the attributes sent.\n\nRequires the `workspaces:write` key ability.", "summary": "Update a workspace", "tags": [ "Workspaces", "Workspace" ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } } ], "requestBody": { "description": "`UpdateWorkspaceRequest`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateWorkspaceRequest" } } } }, "responses": { "200": { "description": "`WorkspaceApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceApiResponse" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/workspaces\/{workspace}\/suspend": { "post": { "operationId": "v1.workspaces.suspend", "description": "Sends and changes in the workspace are refused with `403 workspace_suspended` until it is\nresumed.\n\nRequires the `workspaces:write` key ability.", "summary": "Suspend a workspace", "tags": [ "Workspaces", "Workspace" ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`WorkspaceApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }, "\/workspaces\/{workspace}\/resume": { "post": { "operationId": "v1.workspaces.resume", "description": "Requires the `workspaces:write` key ability.", "summary": "Resume a suspended workspace", "tags": [ "Workspaces", "Workspace" ], "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Workspace-Id", "in": "header", "description": "Platform keys: the workspace (`ws_\u2026`) to act in. Workspace keys may omit it.", "schema": { "type": "string" } }, { "name": "Api-Version", "in": "header", "description": "A dated API version. Defaults to the key's pinned version; the response echoes the version used.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Up to 255 characters. Retrying with the same key and body replays the first response (`Idempotent-Replayed: true`); the same key with a different body is refused with `idempotency_key_reused`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An action on an existing resource: 200, not the POST default of 201.\n\n\n\n`WorkspaceApiResponse`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WorkspaceApiResponse" } } } }, "401": { "description": "The API key is missing, invalid or revoked (`authentication_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "403": { "description": "The key lacks the ability, the plan does not include API access, or the workspace is suspended (`permission_denied`, `workspace_suspended`, `live_key_required`).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "404": { "description": "No such object in this workspace and mode (`resource_missing`). Objects of another workspace or mode are reported as missing, never as forbidden.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "429": { "description": "Too many requests (`rate_limit_exceeded`); retry after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "409": { "description": "The `Idempotency-Key` was used for a different request (`idempotency_key_reused`), or that request is still running (`idempotency_key_in_progress`, retry after `Retry-After` seconds).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "ApiEnvelopeUsageApiResponse": { "type": "object", "description": "The billing account's API and MCP allowance in its current window (not the requested period).", "properties": { "used": { "type": "integer", "description": "API and MCP envelopes sent in the current window, extras included" }, "limit": { "type": [ "integer", "null" ], "description": "The window's allowance; null when API sends count toward the plan's combined allowance" }, "remaining": { "type": [ "integer", "null" ] }, "overage": { "type": "integer", "description": "Envelopes past the allowance, billed as extras" }, "resets_at": { "type": "string" }, "spending_cap": { "anyOf": [ { "description": "Platform plans only: the account's monthly limit on extras", "$ref": "#\/components\/schemas\/ApiSpendingCapApiResponse" }, { "type": "null" } ] } }, "required": [ "used", "limit", "remaining", "overage", "resets_at", "spending_cap" ], "title": "ApiEnvelopeUsageApiResponse" }, "ApiErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "idempotency_error", "api_error" ] }, "code": { "type": "string", "enum": [ "invalid_request", "validation_failed", "resource_missing", "authentication_required", "permission_denied", "workspace_required", "workspace_suspended", "rate_limit_exceeded", "idempotency_key_reused", "idempotency_key_in_progress", "api_version_unsupported", "resource_conflict", "correction_requires_void", "export_in_progress", "api_error", "service_unavailable", "live_key_required" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "doc_url": { "type": "string", "format": "uri" }, "request_id": { "type": "string", "pattern": "^req_[0-9A-HJKMNP-TV-Z]{26}$" }, "quota": { "type": "object", "properties": { "code": { "type": "string", "description": "Which allowance refused the send.", "enum": [ "envelope_limit_reached", "api_envelope_limit_reached", "api_overage_unavailable", "api_spending_cap_reached" ] }, "resets_at": { "type": [ "string", "null" ], "format": "date-time" }, "spending_cap_cents": { "type": "integer", "description": "The Platform spending cap in cents; only with `api_spending_cap_reached`." } }, "required": [ "code", "resets_at" ] } }, "required": [ "type", "code", "message", "param", "doc_url", "request_id" ] } }, "required": [ "error" ], "title": "ApiErrorResponse" }, "ApiKeyApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "name": { "type": "string" }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "envelopes:read", "envelopes:write", "envelopes:send", "envelopes:void", "templates:read", "templates:write", "folders:read", "folders:write", "files:write", "webhooks:read", "webhooks:write", "brand_kits:read", "brand_kits:write", "workspaces:read", "workspaces:write", "workspaces:export", "identity_providers:write", "keys:write", "login_links:write", "usage:read", "artifacts:read", "audit:read", "platform:read" ] } }, "api_version": { "type": "string" }, "workspace": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "api_key" } }, "required": [ "id", "created", "livemode", "name", "abilities", "api_version", "workspace", "platform", "expires_at", "object" ], "title": "ApiKeyApiResponse" }, "ApiSpendingCapApiResponse": { "type": "object", "description": "The account's monthly limit on API extras (Platform). At the limit, API and MCP sends\npast the allowance are refused with `api_spending_cap_reached` until resets_at.", "properties": { "cap_cents": { "type": [ "integer", "null" ], "description": "The limit in cents; null when the account has no limit" }, "used_cents": { "type": "integer", "description": "Extras billed so far this usage month, in cents" }, "remaining_cents": { "type": [ "integer", "null" ] }, "resets_at": { "type": "string" } }, "required": [ "cap_cents", "used_cents", "remaining_cents", "resets_at" ], "title": "ApiSpendingCapApiResponse" }, "ArtifactApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "purpose": { "type": "string" }, "sha256": { "type": "string" }, "size": { "type": "integer" }, "mime_type": { "type": "string" }, "page_count": { "type": [ "integer", "null" ] }, "download_url": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "file" } }, "required": [ "id", "created", "livemode", "purpose", "sha256", "size", "mime_type", "page_count", "download_url", "object" ], "title": "ArtifactApiResponse" }, "AssignFilingRuleApiRequest": { "type": "object", "properties": { "filing_rule": { "type": [ "string", "null" ], "description": "The filing rule (`frl_\u2026`), or `null` to clear it", "pattern": "^frl_[0-9A-HJKMNP-TV-Z]{26}$" } }, "title": "AssignFilingRuleApiRequest" }, "AssignFormFieldsApiRequest": { "type": "object", "description": "`PUT \/api\/v1\/envelopes\/{id}\/form_fields`: the form fields recipients fill, replacing the current\nchoice. Every form field left out stays as it is in the PDF. `acceptance_digest` is the one\n`GET \/envelopes\/{id}\/form_fields` returned, so a choice made from an outdated list is refused.", "properties": { "acceptance_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "fields": { "type": "array", "default": [], "items": { "$ref": "#\/components\/schemas\/FormFieldAssignmentApiData" } } }, "required": [ "acceptance_digest" ], "title": "AssignFormFieldsApiRequest" }, "AssignTemplateFormFieldsApiRequest": { "type": "object", "description": "`PUT \/api\/v1\/templates\/{id}\/form_fields`: the form fields roles fill, replacing the current\nchoice. Every form field left out stays as it is in the PDF. `acceptance_digest` is the one\n`GET \/templates\/{id}\/form_fields` returned.", "properties": { "acceptance_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "fields": { "type": "array", "default": [], "items": { "$ref": "#\/components\/schemas\/TemplateFormFieldAssignmentApiData" } } }, "required": [ "acceptance_digest" ], "title": "AssignTemplateFormFieldsApiRequest" }, "AuditEventApiResponse": { "type": "object", "description": "One entry of the workspace activity log (`aud_\u2026`): sign-ins and memberships through the\nplatform's identity provider, legal holds, retention settings, exports and consent disclosures.\nEnvelope events are in each envelope's audit trail.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "event": { "type": "string", "description": "For example `sso.signed_in`, `legal_hold.set` or `workspace.export_requested`" }, "actor_type": { "type": "string", "description": "`user`, `api_key`, `mcp`, `platform` or `system`" }, "actor": { "type": [ "string", "null" ], "description": "The person (name and email) or the key (`key_\u2026`) that acted; null for the system" }, "subject": { "type": [ "string", "null" ], "description": "The person the event is about, when there is one" }, "ip": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "object": { "type": "string", "default": "audit_event" } }, "required": [ "id", "created", "event", "actor_type", "actor", "subject", "ip", "metadata", "object" ], "title": "AuditEventApiResponse" }, "AuditTrailEntryApiResponse": { "type": "object", "description": "One line of an envelope's audit trail: the same entries as its completion certificate.", "properties": { "event": { "type": "string", "description": "What happened, as the certificate words it" }, "actor": { "type": "string", "description": "Who did it: a name and email, a recipient, `API client` or `System`" }, "ip_address": { "type": [ "string", "null" ] }, "occurred": { "type": "string" }, "object": { "type": "string", "default": "audit_trail_entry" } }, "required": [ "event", "actor", "ip_address", "occurred", "object" ], "title": "AuditTrailEntryApiResponse" }, "BrandKitApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "name": { "type": "string" }, "workspace": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "logo_light_url": { "type": [ "string", "null" ] }, "logo_dark_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "radius_px": { "type": [ "integer", "null" ] }, "font": { "type": [ "string", "null" ] }, "email_header": { "type": [ "string", "null" ] }, "email_footer": { "type": [ "string", "null" ] }, "support_contact": { "type": [ "string", "null" ] }, "show_powered_by": { "type": [ "boolean", "null" ] }, "livemode": { "type": "boolean", "default": true }, "object": { "type": "string", "default": "brand_kit" } }, "required": [ "id", "created", "name", "workspace", "platform", "logo_light_url", "logo_dark_url", "primary_color", "accent_color", "radius_px", "font", "email_header", "email_footer", "support_contact", "show_powered_by", "livemode", "object" ], "title": "BrandKitApiResponse" }, "CcRecipientInputRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "email" ], "title": "CcRecipientInputRequest" }, "ConsentDisclosureApiResponse": { "type": "object", "properties": { "workspace": { "type": "string" }, "version": { "type": "integer" }, "locale": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "agreement_label": { "type": "string" }, "sha256": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "object": { "type": "string", "default": "consent_disclosure" } }, "required": [ "workspace", "version", "locale", "title", "body", "agreement_label", "sha256", "created_at", "livemode", "object" ], "title": "ConsentDisclosureApiResponse" }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "envelopes:read", "envelopes:write", "envelopes:send", "envelopes:void", "templates:read", "templates:write", "folders:read", "folders:write", "files:write", "webhooks:read", "webhooks:write", "brand_kits:read", "brand_kits:write", "workspaces:read", "workspaces:write", "workspaces:export", "identity_providers:write", "keys:write", "login_links:write", "usage:read", "artifacts:read", "audit:read", "platform:read" ] } }, "workspace": { "type": [ "string", "null" ], "pattern": "^ws_[0-9A-HJKMNP-TV-Z]{26}$" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "name", "abilities" ], "title": "CreateApiKeyRequest" }, "CreateConsentDisclosureRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "body": { "type": "string", "maxLength": 20000 }, "agreement_label": { "type": "string", "maxLength": 500 }, "locale": { "type": "string", "enum": [ "en" ], "default": "en" } }, "required": [ "title", "body", "agreement_label" ], "title": "CreateConsentDisclosureRequest" }, "CreateEnvelopeDownloadRequest": { "type": "object", "properties": { "envelopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "envelopes" ], "title": "CreateEnvelopeDownloadRequest" }, "CreateEnvelopeFromTemplateRequest": { "type": "object", "properties": { "recipients": { "type": "array", "default": [], "items": { "$ref": "#\/components\/schemas\/RecipientInputRequestRequest" } }, "cc_recipients": { "type": "array", "default": [], "items": { "$ref": "#\/components\/schemas\/CcRecipientInputRequest" } }, "values": { "type": "object", "default": [], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "null" } ] } }, "signing_order": { "default": "parallel", "$ref": "#\/components\/schemas\/SigningOrder" }, "send": { "type": "boolean", "default": true }, "send_emails": { "type": "boolean", "default": true }, "expires_in_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365 }, "email_subject": { "type": [ "string", "null" ], "maxLength": 255 }, "email_message": { "type": [ "string", "null" ], "maxLength": 5000 }, "external_id": { "type": [ "string", "null" ], "maxLength": 255 }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "folder": { "type": [ "string", "null" ], "description": "The envelope folder (`fdr_\u2026`) to put the envelope in. Absent or null: no folder", "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" } }, "title": "CreateEnvelopeFromTemplateRequest" }, "CreateEnvelopeRequest": { "type": "object", "description": "Creates a draft from a ready file; recipients and fields use their own draft endpoints.", "properties": { "file": { "type": "string", "pattern": "^file_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 255 }, "external_id": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "send_emails": { "type": "boolean", "default": true }, "email_subject": { "type": [ "string", "null" ], "maxLength": 255 }, "email_message": { "type": [ "string", "null" ], "maxLength": 5000 }, "expires_in_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365 }, "use_text_tags": { "type": "boolean", "default": true }, "folder": { "type": [ "string", "null" ], "description": "The envelope folder (`fdr_\u2026`) to put the draft in. Absent or null: no folder", "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "file", "name" ], "title": "CreateEnvelopeRequest" }, "CreateFileRequest": { "type": "object", "description": "`POST \/api\/v1\/files`: a multipart `file` (PDF, office document or image), or a public HTTPS `url` to a PDF.\n`import_form_fields` left out (or true) uses a fillable PDF's own form fields; false uses it as a plain document.", "properties": { "file": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "maxLength": 25600 }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "password": { "type": [ "string", "null" ], "maxLength": 1024 }, "use_text_tags": { "type": "boolean", "default": true }, "import_form_fields": { "type": [ "boolean", "null" ] } }, "title": "CreateFileRequest" }, "CreateFilingRuleApiRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "targets": { "type": "array", "description": "One destination per status; a status left out is not filed", "default": [], "items": { "$ref": "#\/components\/schemas\/FilingRuleTargetApiData" } }, "is_default": { "type": "boolean", "description": "Make this the rule new envelopes start with in the app", "default": false } }, "required": [ "name" ], "title": "CreateFilingRuleApiRequest" }, "CreateFolderApiRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "description": "`envelope` (default) or `template`: what the folder holds", "enum": [ "envelope", "template" ], "default": "envelope" }, "parent": { "type": [ "string", "null" ], "description": "The folder (`fdr_\u2026`) to create it in, of the same type. Null or absent: the top level", "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" }, "use_for_visitor_check_in": { "type": "boolean", "description": "Envelope folders only: file kiosk visitor check-ins here", "default": false } }, "required": [ "name" ], "title": "CreateFolderApiRequest" }, "CreateSigningSessionApiRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "hosted", "embedded" ] }, "return_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "parent_origin": { "type": [ "string", "null" ], "format": "uri", "maxLength": 255 }, "appearance": { "type": "object", "description": "Optional theme tokens on top of the workspace brand kit: `primary` (#rrggbb),\n`radius` (`0px` to `24px`), `font` (`instrument-sans`, `system` or `serif`) and\n`dark_mode` (boolean). `background` is retired: accepted for older callers and ignored", "default": [], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] } }, "actor": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "external_id": { "type": [ "string", "null" ], "maxLength": 255 }, "auth_method": { "type": [ "string", "null" ], "maxLength": 64 } } } }, "required": [ "mode" ], "title": "CreateSigningSessionApiRequest" }, "CreateTemplateApiRequest": { "type": "object", "description": "`POST \/api\/v1\/templates`: a template built from uploaded files (`documents`) or saved from an\nenvelope (`envelope`). Fields are placed afterwards with the template field endpoints.", "properties": { "name": { "type": "string", "maxLength": 255 }, "documents": { "type": [ "array", "null" ], "items": { "$ref": "#\/components\/schemas\/TemplateDocumentApiData" } }, "envelope": { "type": [ "string", "null" ], "pattern": "^env_[0-9A-HJKMNP-TV-Z]{26}$" }, "roles": { "type": [ "array", "null" ], "items": { "$ref": "#\/components\/schemas\/TemplateRoleApiData" } }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "return_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } } }, "required": [ "name" ], "title": "CreateTemplateApiRequest" }, "CreatedApiKeyApiResponse": { "type": "object", "properties": { "secret": { "type": "string" }, "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "name": { "type": "string" }, "abilities": { "type": "array", "items": { "type": "string" } }, "api_version": { "type": "string" }, "workspace": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "api_key" } }, "required": [ "secret", "id", "created", "livemode", "name", "abilities", "api_version", "workspace", "platform", "expires_at", "object" ], "title": "CreatedApiKeyApiResponse" }, "CursorRequest": { "type": "object", "properties": { "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "starting_after": { "type": [ "string", "null" ], "maxLength": 64 }, "ending_before": { "type": [ "string", "null" ], "maxLength": 64 } }, "title": "CursorRequest" }, "DocumentStatus": { "type": "string", "enum": [ "draft", "sent", "completed", "voided", "declined", "expired" ], "title": "DocumentStatus" }, "DraftPreviewSessionApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "revision": { "type": "integer" }, "mode": { "type": "string", "default": "embedded" }, "read_only": { "type": "boolean", "default": true }, "object": { "type": "string", "default": "draft_preview_session" } }, "required": [ "id", "url", "expires_at", "revision", "mode", "read_only", "object" ], "title": "DraftPreviewSessionApiResponse" }, "DuplicateEnvelopeRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 } }, "title": "DuplicateEnvelopeRequest" }, "EditorSessionApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "mode": { "type": "string" }, "target": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": { "type": "boolean" } }, "return_url": { "type": [ "string", "null" ] }, "parent_origin": { "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Single-use. Open it within 10 minutes" }, "expires_at": { "type": "string" }, "object": { "type": "string", "default": "editor_session" } }, "required": [ "id", "created", "livemode", "mode", "target", "capabilities", "return_url", "parent_origin", "url", "expires_at", "object" ], "title": "EditorSessionApiResponse" }, "EmbeddedEnvelopePreviewApiResponse": { "type": "object", "description": "The existing signed download plus an independent, read-only iframe capability.", "properties": { "preview_session": { "$ref": "#\/components\/schemas\/DraftPreviewSessionApiResponse" }, "envelope": { "type": "string" }, "revision": { "type": "integer" }, "page_count": { "type": "integer" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "livemode": { "type": "boolean" }, "object": { "type": "string" } }, "required": [ "preview_session", "envelope", "revision", "page_count", "url", "expires_at", "livemode", "object" ], "title": "EmbeddedEnvelopePreviewApiResponse" }, "EnableTemplateKioskApiRequest": { "type": "object", "description": "`POST \/api\/v1\/templates\/{id}\/kiosk`: turn on Kiosk mode, a walk-up signing page for a shared device.\n`role` may be left out when the template's fields belong to one role. `pin` sets the staff PIN\nthat unlocks the device; leaving it out keeps the current one. The PIN is never returned.", "properties": { "role": { "type": [ "string", "null" ], "maxLength": 255 }, "welcome_message": { "type": [ "string", "null" ], "maxLength": 1000 }, "pin": { "type": [ "string", "null" ], "maxLength": 20 }, "idle_timeout_seconds": { "type": [ "integer", "null" ], "minimum": 30, "maximum": 3600 }, "redirect_delay_seconds": { "type": [ "integer", "null" ], "minimum": 5, "maximum": 120 } }, "title": "EnableTemplateKioskApiRequest" }, "EnableTemplateShareLinkApiRequest": { "type": "object", "description": "`POST \/api\/v1\/templates\/{id}\/share_link`: turn on the public share link. `role` is the role a\nvisitor signs as; it may be left out when the template's fields belong to one role.", "properties": { "role": { "type": [ "string", "null" ], "maxLength": 255 }, "welcome_message": { "type": [ "string", "null" ], "maxLength": 1000 } }, "title": "EnableTemplateShareLinkApiRequest" }, "EnvelopeApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "voided", "declined", "expired" ] }, "workspace": { "type": "string" }, "app_url": { "type": "string", "description": "A link that opens the envelope in the eSignStack app. Signed-in workspace members are taken to it; everyone else gets a 404" }, "template": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "send_emails": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ] }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "recipients": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RecipientApiResponse" } }, "fields": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FieldApiResponse" } }, "documents": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopeDocumentApiResponse" } }, "object": { "type": "string", "default": "envelope" }, "finalization_status": { "type": "string", "enum": [ "pending", "queued", "processing", "completed", "failed" ], "default": "pending" }, "can_retry_finalization": { "type": "boolean", "default": false }, "folder": { "type": [ "string", "null" ], "description": "The envelope folder (`fdr_\u2026`) it is in, or null" }, "filing_rule": { "type": [ "string", "null" ], "description": "The filing rule (`frl_\u2026`) that files it, or null" }, "archived": { "type": "boolean", "description": "Archived envelopes are hidden from lists unless `archived=true`; restore brings them back", "default": false }, "legal_hold": { "type": "boolean", "description": "A legal hold blocks archiving and deletion. It's released only in the app, by an owner or admin", "default": false } }, "required": [ "id", "created", "livemode", "name", "status", "workspace", "app_url", "template", "external_id", "metadata", "send_emails", "expires_at", "notification_policy", "object", "finalization_status", "can_retry_finalization", "folder", "filing_rule", "archived", "legal_hold" ], "title": "EnvelopeApiResponse" }, "EnvelopeArtifactsApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "original_files": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ArtifactApiResponse" } }, "signing_pdf": { "anyOf": [ { "$ref": "#\/components\/schemas\/ArtifactApiResponse" }, { "type": "null" } ] }, "sealed_pdf": { "anyOf": [ { "$ref": "#\/components\/schemas\/ArtifactApiResponse" }, { "type": "null" } ] }, "per_document_pdfs": { "type": "array", "default": [], "items": { "$ref": "#\/components\/schemas\/ArtifactApiResponse" } }, "evidence_json": { "anyOf": [ { "$ref": "#\/components\/schemas\/ArtifactApiResponse" }, { "type": "null" } ] }, "certificate_pdf": { "anyOf": [ { "$ref": "#\/components\/schemas\/ArtifactApiResponse" }, { "type": "null" } ] }, "object": { "type": "string", "default": "envelope_artifacts" } }, "required": [ "id", "created", "livemode", "original_files", "signing_pdf", "sealed_pdf", "per_document_pdfs", "evidence_json", "certificate_pdf", "object" ], "title": "EnvelopeArtifactsApiResponse" }, "EnvelopeCorrectionApiRequest": { "type": "object", "description": "`POST \/api\/v1\/envelopes\/{id}\/corrections` (RFC \u00a75.2.6). `recipients` changes recipients who have\nnot acted (by `id`; only the attributes sent change), `add_recipients` adds recipients to stages\nthat have not started, `remove_recipients` removes recipients who have not acted. An in-person\nsigner's `host_email` names the workspace member who hosts them; it can change until the device is\nhanded to them. Changing `embedded` ends the recipient's current link: turned on, they sign only\nthrough signing sessions; turned off, eSignStack emails them a new one.", "properties": { "remove_recipients": { "type": "array", "default": [], "items": { "type": "string" } }, "note": { "type": [ "string", "null" ], "maxLength": 1000 }, "documents": { "type": [ "array", "null" ], "items": { "$ref": "#\/components\/schemas\/EnvelopeDocumentApiData" } }, "expectedRevision": { "type": [ "integer", "null" ] }, "fields": { "type": [ "array", "null" ], "description": "Full replacement, using the existing document IDs and point geometry.", "items": { "$ref": "#\/components\/schemas\/EnvelopeFieldApiRequestRequest" } }, "recipients": { "type": "array", "default": [], "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "type": { "type": [ "string", "null" ], "enum": [ "signer", "cc", "in_person_signer", "approver", "viewer" ] }, "role": { "type": [ "string", "null" ], "maxLength": 255 }, "auth_method": { "$ref": "#\/components\/schemas\/SignerAuthMethod" }, "auth_access_code": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 50 }, "auth_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "host_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "embedded": { "type": "boolean" } }, "required": [ "id" ] }, "maxItems": 50 }, "add_recipients": { "type": "array", "default": [], "items": { "type": "object", "properties": { "routing_order": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 99 }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "type": { "type": [ "string", "null" ], "enum": [ "signer", "cc", "in_person_signer", "approver", "viewer" ] }, "role": { "type": [ "string", "null" ], "maxLength": 255 }, "auth_method": { "$ref": "#\/components\/schemas\/SignerAuthMethod" }, "auth_access_code": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 50 }, "auth_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "host_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "embedded": { "type": "boolean" } } }, "maxItems": 50 } }, "title": "EnvelopeCorrectionApiRequest" }, "EnvelopeCorrectionApiResponse": { "type": "object", "description": "A correction applied to a sent envelope: the revision it created and what changed.", "properties": { "envelope": { "type": "string" }, "revision": { "type": "integer" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "changed_recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "changed": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "changed" ] } }, "added_recipients": { "type": "array", "items": { "type": "string" } }, "removed_recipients": { "type": "array", "items": { "type": "string" } }, "note": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "envelope_correction" } }, "required": [ "envelope", "revision", "created", "livemode", "changed_recipients", "added_recipients", "removed_recipients", "note", "object" ], "title": "EnvelopeCorrectionApiResponse" }, "EnvelopeDocumentApiData": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "pages": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopePageSourceApiData" } }, "visible_to": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "name", "pages", "visible_to" ], "title": "EnvelopeDocumentApiData" }, "EnvelopeDocumentApiDataRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "pages": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopePageSourceApiDataRequest" } }, "visible_to": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "name", "pages" ], "title": "EnvelopeDocumentApiDataRequest" }, "EnvelopeDocumentApiResponse": { "type": "object", "description": "A document inside an envelope (`doc_\u2026`) with its page manifest. `envelope_page` numbers pages\nacross the whole envelope, the numbering fields use.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "envelope": { "type": "string" }, "position": { "type": "integer" }, "name": { "type": "string" }, "page_count": { "type": "integer" }, "form_policy": { "type": "string" }, "visible_to": { "type": [ "array", "null" ], "items": { "type": "string" } }, "pages": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopePageApiResponse" } }, "object": { "type": "string", "default": "document" } }, "required": [ "id", "created", "livemode", "envelope", "position", "name", "page_count", "form_policy", "visible_to", "pages", "object" ], "title": "EnvelopeDocumentApiResponse" }, "EnvelopeDownloadApiResponse": { "type": "object", "description": "A ZIP of completed envelopes' signed PDFs, behind a short-lived link.", "properties": { "id": { "type": "string", "description": "The download ID (`edl_\u2026`)" }, "envelopes": { "type": "array", "description": "The envelopes in the ZIP, one signed PDF each", "items": { "type": "string" } }, "skipped": { "type": "array", "description": "Requested envelopes left out: not completed, not found, or without a signed PDF", "items": { "type": "string" } }, "url": { "type": "string", "description": "Download the ZIP here, without an API key, until `expires_at`" }, "expires_at": { "type": "string" }, "object": { "type": "string", "default": "envelope_download" } }, "required": [ "id", "envelopes", "skipped", "url", "expires_at", "object" ], "title": "EnvelopeDownloadApiResponse" }, "EnvelopeFieldApiRequest": { "type": "object", "description": "Create (`POST`) or change (`PATCH`) a field. Geometry is in PDF points from the top-left of the\ndisplayed page; `page` is within `document` and may be negative to count from the end.", "properties": { "type": { "$ref": "#\/components\/schemas\/EnvelopeFieldType" }, "recipient": { "type": [ "string", "null" ] }, "prefill": { "type": "boolean" }, "document": { "type": [ "string", "null" ] }, "page": { "type": "integer" }, "x": { "type": "number", "minimum": 0 }, "y": { "type": "number", "minimum": 0 }, "width": { "type": "number" }, "height": { "type": "number" }, "label": { "type": [ "string", "null" ], "pattern": "^[^.\\p{Cc}]+$", "maxLength": 255 }, "required": { "type": "boolean" }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "value": { "type": [ "string", "null" ], "maxLength": 5000 }, "validation": { "anyOf": [ { "$ref": "#\/components\/schemas\/FieldValidationApiData" }, { "type": "null" } ] }, "tab_order": { "type": [ "integer", "null" ], "minimum": 1 } }, "title": "EnvelopeFieldApiRequest" }, "EnvelopeFieldApiRequestRequest": { "type": "object", "description": "Create (`POST`) or change (`PATCH`) a field. Geometry is in PDF points from the top-left of the\ndisplayed page; `page` is within `document` and may be negative to count from the end.", "properties": { "type": { "$ref": "#\/components\/schemas\/EnvelopeFieldType" }, "recipient": { "type": [ "string", "null" ] }, "prefill": { "type": "boolean" }, "document": { "type": [ "string", "null" ] }, "page": { "type": "integer" }, "x": { "type": "number", "minimum": 0 }, "y": { "type": "number", "minimum": 0 }, "width": { "type": "number" }, "height": { "type": "number" }, "label": { "type": [ "string", "null" ], "pattern": "^[^.\\p{Cc}]+$", "maxLength": 255 }, "required": { "type": "boolean" }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "value": { "type": [ "string", "null" ], "maxLength": 5000 }, "validation": { "anyOf": [ { "$ref": "#\/components\/schemas\/FieldValidationApiDataRequest" }, { "type": "null" } ] }, "tab_order": { "type": [ "integer", "null" ], "minimum": 1 } }, "title": "EnvelopeFieldApiRequestRequest" }, "EnvelopeFieldType": { "type": "string", "enum": [ "signature", "date", "text", "initials", "checkbox", "dropdown", "date_signed", "email", "name", "radio_group", "checkbox_group", "number", "attachment", "company", "title", "repeat_group" ], "title": "EnvelopeFieldType" }, "EnvelopeFormFieldsApiResponse": { "type": "object", "description": "The fields of an envelope's PDF form (`GET \/envelopes\/{id}\/form_fields`), one entry per form\nfield. `policy` is `native` when the form's fields can be filled here, `static_appearances` when\nthey are kept as they look in the file, `flat` when it has none, and null when the envelope has no\nform report.\n\nSend `acceptance_digest` back with `PUT \/envelopes\/{id}\/form_fields`. When `requires_acceptance`\nis true (a digitally signed upload or a converted XFA form, explained in `notices`), that call\nalso accepts the report for the key, which sending needs.", "properties": { "envelope": { "type": "string" }, "policy": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "assigned_count": { "type": "integer" }, "acceptance_digest": { "type": "string" }, "requires_acceptance": { "type": "boolean" }, "accepted": { "type": "boolean" }, "notices": { "type": "array", "items": { "type": "string" } }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FormFieldApiResponse" } }, "object": { "type": "string", "default": "envelope_form_fields" } }, "required": [ "envelope", "policy", "count", "assigned_count", "acceptance_digest", "requires_acceptance", "accepted", "notices", "data", "object" ], "title": "EnvelopeFormFieldsApiResponse" }, "EnvelopePageApiResponse": { "type": "object", "description": "One page of an envelope document: where it comes from and its displayed size in points.", "properties": { "position": { "type": "integer" }, "envelope_page": { "type": "integer" }, "file": { "type": [ "string", "null" ] }, "source_page": { "type": "integer" }, "rotation": { "type": "integer" }, "width_pt": { "type": "number" }, "height_pt": { "type": "number" } }, "required": [ "position", "envelope_page", "file", "source_page", "rotation", "width_pt", "height_pt" ], "title": "EnvelopePageApiResponse" }, "EnvelopePageSourceApiData": { "type": "object", "description": "A page for an envelope document: page `page` of an uploaded `file`, or of a `document` already\nin the envelope.", "properties": { "page": { "type": "integer", "minimum": 1 }, "file": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "rotation": { "type": "integer", "enum": [ "0", "90", "180", "270" ], "default": 0 } }, "required": [ "page", "file", "document", "rotation" ], "title": "EnvelopePageSourceApiData" }, "EnvelopePageSourceApiDataRequest": { "type": "object", "description": "A page for an envelope document: page `page` of an uploaded `file`, or of a `document` already\nin the envelope.", "properties": { "page": { "type": "integer", "minimum": 1 }, "file": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "rotation": { "type": "integer", "enum": [ "0", "90", "180", "270" ], "default": 0 } }, "required": [ "page" ], "title": "EnvelopePageSourceApiDataRequest" }, "EnvelopePreviewApiResponse": { "type": "object", "description": "A watermarked preview of a draft (RFC \u00a75.2.6). `revision` is the draft revision it shows; a draft\nwith a higher revision has changed since.", "properties": { "envelope": { "type": "string" }, "revision": { "type": "integer" }, "page_count": { "type": "integer" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "livemode": { "type": "boolean" }, "object": { "type": "string", "default": "envelope_preview" } }, "required": [ "envelope", "revision", "page_count", "url", "expires_at", "livemode", "object" ], "title": "EnvelopePreviewApiResponse" }, "EnvelopeRecipientApiRequest": { "type": "object", "description": "Add (`POST`) or change (`PATCH`) a recipient of a draft envelope (RFC \u00a75.2.4).", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "type": { "type": "string", "enum": [ "signer", "cc", "in_person_signer", "approver", "viewer" ] }, "role": { "type": [ "string", "null" ], "maxLength": 255 }, "routing_order": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 99 }, "receive_completed_pdf": { "type": "boolean" }, "auth_method": { "anyOf": [ { "$ref": "#\/components\/schemas\/SignerAuthMethod" }, { "type": "null" } ] }, "auth_access_code": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 50 }, "auth_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "documents": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allow_delegation": { "type": "boolean" }, "host_email": { "type": [ "string", "null" ], "format": "email", "description": "An `in_person_signer`'s host: the email address of a workspace member. Defaults to the envelope's sender", "maxLength": 255 }, "embedded": { "type": "boolean", "description": "Signs only in your app through signing sessions; eSignStack never emails them a signing link. Not for `cc` or `in_person_signer`" } }, "title": "EnvelopeRecipientApiRequest" }, "EventApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created": { "type": "string" }, "api_version": { "type": "string" }, "livemode": { "type": "boolean" }, "platform": { "type": [ "string", "null" ] }, "workspace": { "type": [ "string", "null" ] }, "data": { "type": "object", "additionalProperties": {} }, "object": { "type": "string", "default": "event" } }, "required": [ "id", "type", "created", "api_version", "livemode", "platform", "workspace", "data", "object" ], "title": "EventApiResponse" }, "ExtendEnvelopeRequest": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 365 }, "notify_pending_signers": { "type": "boolean", "default": false } }, "required": [ "days" ], "title": "ExtendEnvelopeRequest" }, "FieldApiResponse": { "type": "object", "description": "A placed field (`fld_\u2026`). `box` is in PDF points from the top-left of the displayed page\n(RFC \u00a75.3.2); `page` counts within `document`, `envelope_page` across the envelope.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "envelope": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] }, "envelope_page": { "type": "integer" }, "box": { "type": [ "object", "null" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ] }, "type": { "type": "string", "enum": [ "signature", "date", "text", "initials", "checkbox", "dropdown", "date_signed", "email", "name", "radio_group", "checkbox_group", "number", "attachment", "company", "title", "repeat_group" ] }, "recipient": { "type": [ "string", "null" ] }, "prefill": { "type": "boolean" }, "label": { "type": [ "string", "null" ] }, "required": { "type": "boolean" }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "value": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "manual", "acroform", "text_tag", "xfa", "template", "ai_suggestion", "api" ] }, "native_field_name": { "type": [ "string", "null" ] }, "validation": { "type": [ "object", "null" ], "additionalProperties": {} }, "tab_order": { "type": [ "integer", "null" ] }, "object": { "type": "string", "default": "field" } }, "required": [ "id", "created", "livemode", "envelope", "document", "page", "envelope_page", "box", "type", "recipient", "prefill", "label", "required", "options", "value", "source", "native_field_name", "validation", "tab_order", "object" ], "title": "FieldApiResponse" }, "FieldPattern": { "type": "string", "description": "The fixed list of formats a text field can require (RFC \u00a75.3.1). Free regular expressions are a template-only feature, kept separately as `customPattern`.\n", "enum": [ "email", "phone", "us_zip", "ssn_last4", "date_iso", "date_us" ], "title": "FieldPattern" }, "FieldValidationApiData": { "type": "object", "description": "A field's validation rules in the API's snake_case (RFC \u00a75.3.1).", "properties": { "read_only": { "type": "boolean", "default": false }, "max_length": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5000 }, "pattern": { "anyOf": [ { "$ref": "#\/components\/schemas\/FieldPattern" }, { "type": "null" } ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "decimals": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6 }, "min_selected": { "type": [ "integer", "null" ], "minimum": 0 }, "max_selected": { "type": [ "integer", "null" ], "minimum": 1 }, "min_rows": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 50 }, "max_rows": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "visible_if": { "type": "object", "properties": { "field": { "type": "string", "maxLength": 255 }, "equals": { "type": "string", "maxLength": 255 } } }, "columns": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "maxLength": 100 }, "type": { "$ref": "#\/components\/schemas\/RepeatGroupColumnType" }, "required": { "type": [ "boolean", "null" ] } }, "required": [ "key", "label" ] }, "maxItems": 10 } }, "required": [ "read_only", "max_length", "pattern", "min", "max", "decimals", "min_selected", "max_selected", "min_rows", "max_rows", "visible_if", "columns" ], "title": "FieldValidationApiData" }, "FieldValidationApiDataRequest": { "type": "object", "description": "A field's validation rules in the API's snake_case (RFC \u00a75.3.1).", "properties": { "read_only": { "type": "boolean", "default": false }, "max_length": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5000 }, "pattern": { "anyOf": [ { "$ref": "#\/components\/schemas\/FieldPattern" }, { "type": "null" } ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "decimals": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6 }, "min_selected": { "type": [ "integer", "null" ], "minimum": 0 }, "max_selected": { "type": [ "integer", "null" ], "minimum": 1 }, "min_rows": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 50 }, "max_rows": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "visible_if": { "type": "object", "properties": { "field": { "type": "string", "maxLength": 255 }, "equals": { "type": "string", "maxLength": 255 } } }, "columns": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "maxLength": 100 }, "type": { "$ref": "#\/components\/schemas\/RepeatGroupColumnType" }, "required": { "type": [ "boolean", "null" ] } }, "required": [ "key", "label" ] }, "maxItems": 10 } }, "title": "FieldValidationApiDataRequest" }, "FileApiResponse": { "type": "object", "description": "An uploaded file (`file_\u2026`) and what inspection found in it.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "status": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer" }, "page_count": { "type": [ "integer", "null" ] }, "inspection": { "type": [ "object", "null" ], "additionalProperties": {} }, "failure": { "type": [ "array", "null" ], "items": { "type": "string" } }, "object": { "type": "string", "default": "file" } }, "required": [ "id", "created", "livemode", "status", "filename", "mime_type", "size", "page_count", "inspection", "failure", "object" ], "title": "FileApiResponse" }, "FilingRuleApiResponse": { "type": "object", "description": "A filing rule (`frl_\u2026`): for each envelope status it maps, envelopes using the rule move to that\nfolder when they reach the status. `is_default` marks the rule new envelopes start with in the\napp. Shared by both modes, so `livemode` is always true.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "targets": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FilingRuleTargetApiResponse" } }, "workspace": { "type": "string" }, "livemode": { "type": "boolean", "default": true }, "object": { "type": "string", "default": "filing_rule" } }, "required": [ "id", "created", "name", "is_default", "targets", "workspace", "livemode", "object" ], "title": "FilingRuleApiResponse" }, "FilingRuleTargetApiData": { "type": "object", "properties": { "status": { "type": "string", "description": "An envelope status: `sent`, `completed`, `voided`, `declined` or `expired`" }, "folder": { "type": "string", "description": "The envelope folder (`fdr_\u2026`) to file envelopes in when they reach the status" } }, "required": [ "status", "folder" ], "title": "FilingRuleTargetApiData" }, "FilingRuleTargetApiResponse": { "type": "object", "description": "Where a filing rule moves an envelope when it reaches `status`.", "properties": { "status": { "type": "string", "enum": [ "sent", "completed", "voided", "declined", "expired" ] }, "folder": { "type": "string", "description": "The destination envelope folder (`fdr_\u2026`)" } }, "required": [ "status", "folder" ], "title": "FilingRuleTargetApiResponse" }, "FolderApiResponse": { "type": "object", "description": "A folder (`fdr_\u2026`) of envelopes or of templates. Folders nest through `parent` (null at the top\nlevel). Like the app, one set of folders serves both modes, so `livemode` is always true.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "description": "`envelope` or `template`: what the folder holds", "enum": [ "envelope", "template" ] }, "parent": { "type": [ "string", "null" ] }, "workspace": { "type": "string" }, "use_for_visitor_check_in": { "type": "boolean" }, "livemode": { "type": "boolean", "default": true }, "object": { "type": "string", "default": "folder" } }, "required": [ "id", "created", "name", "type", "parent", "workspace", "use_for_visitor_check_in", "livemode", "object" ], "title": "FolderApiResponse" }, "FormFieldApiResponse": { "type": "object", "description": "One field of the PDF's own form, found when the file was uploaded. A form field can have several\nboxes (`widgets`): a radio button per choice, or a check box repeated on several pages. Each box\nis an envelope field (`fld_\u2026`); `page`, `envelope_page` and `box` are the first box's, in PDF points\nfrom the top-left of the page, as for placed fields.\n\n`name` identifies the field in this envelope (a form in a document of several gets a document\nprefix); `pdf_name` is its name in the uploaded PDF. `status` is `assigned` (a recipient fills it), `kept` (it stays as it is in the PDF, with its\ncurrent value) or `unassigned`. `can_keep` is false for fields only a recipient can complete,\nsuch as signatures.", "properties": { "name": { "type": "string" }, "pdf_name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "signature", "date", "text", "initials", "checkbox", "dropdown", "date_signed", "email", "name", "radio_group", "checkbox_group", "number", "attachment", "company", "title", "repeat_group" ] }, "pdf_type": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] }, "envelope_page": { "type": "integer" }, "box": { "type": [ "object", "null" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ] }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] }, "envelope_page": { "type": "integer" }, "box": { "type": [ "object", "null" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ] }, "label": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] } }, "required": [ "field", "document", "page", "envelope_page", "box", "label", "state" ] } }, "value": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "required": { "type": "boolean" }, "read_only": { "type": "boolean" }, "status": { "type": "string", "enum": [ "assigned", "kept", "unassigned" ] }, "recipient": { "type": [ "string", "null" ] }, "can_keep": { "type": "boolean" }, "object": { "type": "string", "default": "form_field" } }, "required": [ "name", "pdf_name", "label", "type", "pdf_type", "document", "page", "envelope_page", "box", "widgets", "value", "options", "required", "read_only", "status", "recipient", "can_keep", "object" ], "title": "FormFieldApiResponse" }, "FormFieldAssignmentApiData": { "type": "object", "description": "One chosen form field: its `name` from `GET \/envelopes\/{id}\/form_fields` and the recipient who\nfills it. `required` and `label` change the field; left out, they stay as they are.", "properties": { "name": { "type": "string", "maxLength": 1024 }, "recipient": { "type": "string", "pattern": "^rcp_[0-9A-HJKMNP-TV-Z]{26}$" }, "required": { "type": [ "boolean", "null" ] }, "label": { "type": [ "string", "null" ], "pattern": "^[^.\\p{Cc}]+$", "maxLength": 255 } }, "required": [ "name", "recipient" ], "title": "FormFieldAssignmentApiData" }, "IdentityProviderApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "display_name": { "type": "string" }, "issuer": { "type": "string" }, "client_id": { "type": "string" }, "tenant_claim": { "type": "string" }, "role_mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "require_for_platform_workspaces": { "type": "boolean" }, "platform_role_claim": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "callback_url": { "type": "string" }, "start_url": { "type": "string" }, "backchannel_logout_url": { "type": "string" }, "login_url": { "type": [ "string", "null" ] }, "console_mfa_amr": { "type": "array", "items": { "type": "string" } }, "console_mfa_acr": { "type": "array", "items": { "type": "string" } }, "object": { "type": "string", "default": "identity_provider" }, "livemode": { "type": "boolean", "default": true }, "created": { "type": [ "string", "null" ] } }, "required": [ "id", "platform", "display_name", "issuer", "client_id", "tenant_claim", "role_mapping", "require_for_platform_workspaces", "platform_role_claim", "logo_url", "status", "callback_url", "start_url", "backchannel_logout_url", "login_url", "console_mfa_amr", "console_mfa_acr", "object", "livemode", "created" ], "title": "IdentityProviderApiResponse" }, "IndexAuditEventsRequest": { "type": "object", "properties": { "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "starting_after": { "type": [ "string", "null" ], "maxLength": 64 }, "ending_before": { "type": [ "string", "null" ], "maxLength": 64 }, "filter": { "type": "object", "properties": { "event": { "type": [ "string", "null" ], "description": "Only this event, for example `legal_hold.set`", "maxLength": 100 } } } }, "required": [ "limit" ], "title": "IndexAuditEventsRequest" }, "IndexConsentDisclosuresRequest": { "type": "object", "properties": { "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "before_version": { "type": [ "integer", "null" ], "minimum": 1 } }, "title": "IndexConsentDisclosuresRequest" }, "IndexEnvelopesRequest": { "type": "object", "properties": { "expand": { "type": "array", "default": [], "items": { "type": "string" } }, "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "starting_after": { "type": [ "string", "null" ], "pattern": "^env_[0-9A-HJKMNP-TV-Z]{26}$" }, "ending_before": { "type": [ "string", "null" ], "pattern": "^env_[0-9A-HJKMNP-TV-Z]{26}$" }, "filter": { "type": "object", "properties": { "status": { "anyOf": [ { "description": "Only envelopes in this status", "$ref": "#\/components\/schemas\/DocumentStatus" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ], "description": "Only envelopes with your own reference", "maxLength": 255 }, "template": { "type": [ "string", "null" ], "description": "Only envelopes made from this template (`tpl_\u2026`)", "pattern": "^tpl_[0-9A-HJKMNP-TV-Z]{26}$" }, "created": { "type": "object", "description": "Created within these bounds: `gte`, `lte` or both", "default": [], "properties": { "gte": { "type": "string", "format": "date-time" }, "lte": { "type": "string", "format": "date-time" } } }, "metadata": { "type": "object", "description": "Every given metadata key has this value", "default": [], "additionalProperties": { "type": "string" } }, "archived": { "type": [ "string", "null" ], "description": "`true` lists only archived envelopes", "enum": [ "true", "false", "1", "0" ] } } } }, "required": [ "limit" ], "title": "IndexEnvelopesRequest" }, "IndexEventsRequest": { "type": "object", "properties": { "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "starting_after": { "type": [ "string", "null" ], "maxLength": 64 }, "ending_before": { "type": [ "string", "null" ], "maxLength": 64 }, "filter": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "Only this event type, for example `envelope.completed`", "maxLength": 64 }, "object": { "type": [ "string", "null" ], "description": "Only events about this object (an envelope, recipient or template ID)", "maxLength": 64 }, "created": { "type": "object", "description": "Created within these bounds (`gt`, `gte`, `lt`, `lte`): an ISO 8601 date or a Unix timestamp", "default": [], "properties": { "gt": { "type": "string", "maxLength": 64 }, "gte": { "type": "string", "maxLength": 64 }, "lt": { "type": "string", "maxLength": 64 }, "lte": { "type": "string", "maxLength": 64 } } } } } }, "required": [ "limit" ], "title": "IndexEventsRequest" }, "IndexFoldersRequest": { "type": "object", "properties": { "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "starting_after": { "type": [ "string", "null" ], "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" }, "ending_before": { "type": [ "string", "null" ], "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" }, "filter": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "Only `envelope` or only `template` folders", "enum": [ "envelope", "template" ] }, "parent": { "type": [ "string", "null" ], "description": "Only the folders directly inside this folder (`fdr_\u2026`)", "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" } } } }, "required": [ "limit" ], "title": "IndexFoldersRequest" }, "IndexPlatformMembersRequest": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "role": { "anyOf": [ { "description": "Only members with this role", "$ref": "#\/components\/schemas\/PlatformRole" }, { "type": "null" } ] } } } }, "title": "IndexPlatformMembersRequest" }, "IndexTemplatesRequest": { "type": "object", "properties": { "expand": { "type": "array", "default": [], "items": { "type": "string" } }, "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "starting_after": { "type": [ "string", "null" ], "pattern": "^tpl_[0-9A-HJKMNP-TV-Z]{26}$" }, "ending_before": { "type": [ "string", "null" ], "pattern": "^tpl_[0-9A-HJKMNP-TV-Z]{26}$" }, "filter": { "type": "object", "properties": { "created": { "type": "object", "description": "Created within these bounds: `gte`, `lte` or both", "default": [], "properties": { "gte": { "type": "string", "format": "date-time" }, "lte": { "type": "string", "format": "date-time" } } }, "metadata": { "type": "object", "description": "Every given metadata key has this value", "default": [], "additionalProperties": { "type": "string" } }, "archived": { "type": [ "string", "null" ], "description": "`true` lists only archived templates", "enum": [ "true", "false", "1", "0" ] } } } }, "required": [ "limit" ], "title": "IndexTemplatesRequest" }, "LoginLinkApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "workspace": { "type": "string" }, "url": { "type": "string", "description": "Single-use. Valid for 60 seconds" }, "expires_at": { "type": "string" }, "object": { "type": "string", "default": "login_link" } }, "required": [ "id", "created", "workspace", "url", "expires_at", "object" ], "title": "LoginLinkApiResponse" }, "MoveToFolderApiRequest": { "type": "object", "properties": { "folder": { "type": [ "string", "null" ], "description": "The destination folder (`fdr_\u2026`), or `null` to move out of every folder", "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" } }, "title": "MoveToFolderApiRequest" }, "PdfDocumentTimestampResponse": { "type": "object", "properties": { "genTime": { "type": "string" }, "accuracy": { "anyOf": [ { "$ref": "#\/components\/schemas\/PdfTimestampAccuracyResponse" }, { "type": "null" } ] }, "policyOid": { "type": "string" }, "serialNumber": { "type": "string" }, "imprintAlgorithm": { "type": [ "string", "null" ] }, "imprintMatches": { "type": "boolean" }, "tsa": { "anyOf": [ { "$ref": "#\/components\/schemas\/PdfTimestampIdentityResponse" }, { "type": "null" } ] }, "tsaCertificateSha256": { "type": "string" } }, "required": [ "genTime", "accuracy", "policyOid", "serialNumber", "imprintAlgorithm", "imprintMatches", "tsa", "tsaCertificateSha256" ], "title": "PdfDocumentTimestampResponse" }, "PdfSignatureResponse": { "type": "object", "properties": { "kind": { "type": "string" }, "integrity": { "type": "string" }, "coverage": { "type": "string" }, "laterRevisions": { "type": "integer" }, "trusted": { "type": [ "boolean", "null" ] }, "time": { "type": [ "string", "null" ] }, "modifications": { "type": [ "string", "null" ] }, "certificationRespected": { "type": [ "boolean", "null" ] }, "locksRespected": { "type": [ "boolean", "null" ] }, "trustStatus": { "type": "string" }, "timeStatus": { "type": "string" }, "evaluationReason": { "type": [ "string", "null" ] }, "upstreamIssue": { "type": [ "string", "null" ] }, "documentTimestamp": { "anyOf": [ { "$ref": "#\/components\/schemas\/PdfDocumentTimestampResponse" }, { "type": "null" } ] }, "trustFailureReasons": { "type": "array", "default": [], "items": { "type": "string" } }, "revocationStatus": { "type": [ "string", "null" ] } }, "required": [ "kind", "integrity", "coverage", "laterRevisions", "trusted", "time", "modifications", "certificationRespected", "locksRespected", "trustStatus", "timeStatus", "evaluationReason", "upstreamIssue", "documentTimestamp", "trustFailureReasons", "revocationStatus" ], "title": "PdfSignatureResponse" }, "PdfSignatureValidationResponse": { "type": "object", "properties": { "allIntact": { "type": "boolean" }, "timestampCoversFile": { "type": [ "boolean", "null" ] }, "revisions": { "type": "integer" }, "unframedTailBytes": { "type": "integer" }, "hiddenSignatures": { "type": "integer" }, "signatures": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PdfSignatureResponse" } }, "assessedAt": { "type": [ "string", "null" ] }, "policyFingerprint": { "type": [ "string", "null" ] } }, "required": [ "allIntact", "timestampCoversFile", "revisions", "unframedTailBytes", "hiddenSignatures", "signatures", "assessedAt", "policyFingerprint" ], "title": "PdfSignatureValidationResponse" }, "PdfTimestampAccuracyResponse": { "type": "object", "properties": { "seconds": { "type": "integer" }, "millis": { "type": "integer" }, "micros": { "type": "integer" } }, "required": [ "seconds", "millis", "micros" ], "title": "PdfTimestampAccuracyResponse" }, "PdfTimestampIdentityResponse": { "type": "object", "properties": { "subject": { "type": "array", "items": { "type": "string" } }, "issuer": { "type": "array", "items": { "type": "string" } }, "serialNumber": { "type": "string" }, "certificateSha256": { "type": "string" }, "validFrom": { "type": "string" }, "validTo": { "type": "string" } }, "required": [ "subject", "issuer", "serialNumber", "certificateSha256", "validFrom", "validTo" ], "title": "PdfTimestampIdentityResponse" }, "PlatformApiResponse": { "type": "object", "description": "The platform's console settings, read-only. Changing them stays in the platform console.", "properties": { "id": { "type": "string", "description": "The platform ID (`plat_\u2026`)" }, "created": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "description": "`active` or `suspended`" }, "plan": { "type": "string" }, "members_may_create_workspaces": { "type": "boolean", "description": "Whether platform members may create workspaces in the console" }, "default_brand_kit": { "type": [ "string", "null" ], "description": "The brand kit (`bk_\u2026`) workspaces without their own kit use" }, "object": { "type": "string", "default": "platform" } }, "required": [ "id", "created", "name", "status", "plan", "members_may_create_workspaces", "default_brand_kit", "object" ], "title": "PlatformApiResponse" }, "PlatformMemberApiResponse": { "type": "object", "description": "A person with access to the platform console. Invitations and role changes stay in the console.", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "description": "`admin`, `developer`, `support` or `billing`" }, "joined": { "type": [ "string", "null" ], "description": "When the person joined the platform" }, "object": { "type": "string", "default": "platform_member" } }, "required": [ "name", "email", "role", "joined", "object" ], "title": "PlatformMemberApiResponse" }, "PlatformRole": { "type": "string", "enum": [ "admin", "developer", "billing", "support" ], "title": "PlatformRole" }, "PlatformUsageApiResponse": { "type": "object", "description": "A platform's own API allowance. API and MCP sends in every workspace the platform manages\ncount toward its Platform plan, not toward the workspaces.", "properties": { "id": { "type": "string", "description": "The platform ID (`plat_\u2026`)" }, "livemode": { "type": "boolean" }, "api_envelopes": { "anyOf": [ { "description": "The Platform plan's API allowance, extras and spending cap; null when the platform has no billing account linked", "$ref": "#\/components\/schemas\/ApiEnvelopeUsageApiResponse" }, { "type": "null" } ] }, "object": { "type": "string", "default": "platform_usage" } }, "required": [ "id", "livemode", "api_envelopes", "object" ], "title": "PlatformUsageApiResponse" }, "PreviewEnvelopeApiRequest": { "type": "object", "properties": { "parent_origin": { "type": [ "string", "null" ], "format": "uri", "maxLength": 255 } }, "title": "PreviewEnvelopeApiRequest" }, "PublicVerificationEventResponse": { "type": "object", "description": "One audit event on the public verify page: no email, IP or device, and names masked.", "properties": { "occurredAt": { "type": "string" }, "event": { "type": "string" }, "actor": { "type": "string" } }, "required": [ "occurredAt", "event", "actor" ], "title": "PublicVerificationEventResponse" }, "PublicVerificationResponse": { "type": "object", "properties": { "mode": { "$ref": "#\/components\/schemas\/VerificationMode" }, "summary": { "anyOf": [ { "$ref": "#\/components\/schemas\/PublicVerificationSummaryResponse" }, { "type": "null" } ] }, "validation": { "anyOf": [ { "$ref": "#\/components\/schemas\/PdfSignatureValidationResponse" }, { "type": "null" } ] }, "exactMatch": { "type": [ "boolean", "null" ] }, "auditChainValid": { "type": [ "boolean", "null" ] }, "verifiedSha256": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "state": { "default": "ready", "$ref": "#\/components\/schemas\/VerificationState" }, "recordedValidation": { "anyOf": [ { "$ref": "#\/components\/schemas\/PdfSignatureValidationResponse" }, { "type": "null" } ] } }, "required": [ "mode", "summary", "validation", "exactMatch", "auditChainValid", "verifiedSha256", "message", "state", "recordedValidation" ], "title": "PublicVerificationResponse" }, "PublicVerificationSummaryResponse": { "type": "object", "properties": { "status": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "envelopeNames": { "type": "array", "items": { "type": "string" } }, "signerCount": { "type": "integer" }, "maskedSignerNames": { "type": "array", "items": { "type": "string" } }, "recordedTimestamped": { "type": "boolean" }, "events": { "type": "array", "default": [], "items": { "$ref": "#\/components\/schemas\/PublicVerificationEventResponse" } } }, "required": [ "status", "completedAt", "envelopeNames", "signerCount", "maskedSignerNames", "recordedTimestamped", "events" ], "title": "PublicVerificationSummaryResponse" }, "RecipientApiResponse": { "type": "object", "description": "A recipient (`rcp_\u2026`). Signing links, tokens and access codes are never part of it; `auth_method`\nnames the method only.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "signer", "cc", "in_person_signer", "approver", "viewer", "witness" ] }, "status": { "type": "string", "enum": [ "pending", "sent", "signed", "approved", "acknowledged", "declined" ] }, "role": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "routing_order": { "type": "integer", "default": 1 }, "auth_method": { "type": [ "string", "null" ] }, "receive_completed_pdf": { "type": "boolean", "default": true }, "signed_at": { "type": [ "string", "null" ] }, "decline_reason": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "recipient" }, "completed_at": { "type": [ "string", "null" ] }, "allow_delegation": { "type": "boolean", "default": false }, "host": { "type": [ "object", "null" ], "description": "An `in_person_signer`'s host, the workspace member who hands over their device; null for\neveryone else", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ] }, "embedded": { "type": "boolean", "description": "Signs only in your app through signing sessions: eSignStack sends them no invitation, reminder or \"your turn\" email", "default": false } }, "required": [ "id", "created", "livemode", "name", "email", "type", "status", "role", "metadata", "routing_order", "auth_method", "receive_completed_pdf", "signed_at", "decline_reason", "object", "completed_at", "allow_delegation", "host", "embedded" ], "title": "RecipientApiResponse" }, "RecipientInputRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Required, except for an in-person signer's role, where it is only for their copy", "maxLength": 255 }, "role_label": { "type": "string", "maxLength": 255 }, "auth_method": { "anyOf": [ { "$ref": "#\/components\/schemas\/SignerAuthMethod" }, { "type": "null" } ] }, "access_code": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 50 }, "auth_phone": { "type": [ "string", "null" ], "maxLength": 20 }, "receive_completed_pdf": { "type": "boolean", "default": true }, "allow_delegation": { "type": "boolean" }, "host_email": { "type": [ "string", "null" ], "format": "email", "description": "An in-person signer's host: the email address of a member of the workspace", "maxLength": 255 }, "embedded": { "type": "boolean", "description": "Signs only in your app through signing sessions; eSignStack never emails them a signing link. Not for CC or in-person roles", "default": false } }, "required": [ "name", "email", "role_label", "auth_method", "access_code", "auth_phone", "receive_completed_pdf", "host_email", "embedded" ], "title": "RecipientInputRequest" }, "RecipientInputRequestRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Required, except for an in-person signer's role, where it is only for their copy", "maxLength": 255 }, "role_label": { "type": "string", "maxLength": 255 }, "auth_method": { "anyOf": [ { "$ref": "#\/components\/schemas\/SignerAuthMethod" }, { "type": "null" } ] }, "access_code": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 50 }, "auth_phone": { "type": [ "string", "null" ], "maxLength": 20 }, "receive_completed_pdf": { "type": "boolean", "default": true }, "allow_delegation": { "type": "boolean" }, "host_email": { "type": [ "string", "null" ], "format": "email", "description": "An in-person signer's host: the email address of a member of the workspace", "maxLength": 255 }, "embedded": { "type": "boolean", "description": "Signs only in your app through signing sessions; eSignStack never emails them a signing link. Not for CC or in-person roles", "default": false } }, "required": [ "name", "role_label" ], "title": "RecipientInputRequestRequest" }, "RemindEnvelopeRequest": { "type": "object", "properties": { "recipient": { "type": [ "string", "null" ], "pattern": "^rcp_[0-9A-HJKMNP-TV-Z]{26}$" } }, "title": "RemindEnvelopeRequest" }, "RepeatGroupColumnType": { "type": "string", "description": "What one column of a repeating group holds (RFC \u00a75.3.1, \u00a79.4 item 3).\n", "enum": [ "text", "date", "number", "email" ], "title": "RepeatGroupColumnType" }, "SaveIdentityProviderRequest": { "type": "object", "properties": { "display_name": { "type": "string", "maxLength": 120 }, "issuer": { "type": "string", "format": "uri", "maxLength": 2048 }, "client_id": { "type": "string", "maxLength": 255 }, "client_secret": { "type": [ "string", "null" ], "maxLength": 1024 }, "tenant_claim": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.:-]+$", "maxLength": 64 }, "role_mapping": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "require_for_platform_workspaces": { "type": "boolean", "default": true }, "platform_role_claim": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.:-]+$", "maxLength": 64 }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "console_mfa_amr": { "type": "array", "items": { "type": "string" } }, "console_mfa_acr": { "type": "array", "items": { "type": "string" } } }, "required": [ "display_name", "issuer", "client_id" ], "title": "SaveIdentityProviderRequest" }, "SetEnvelopeDocumentsApiRequest": { "type": "object", "description": "`PUT \/api\/v1\/envelopes\/{id}\/documents`: the envelope's documents and their pages, replacing the\ncurrent manifest.", "properties": { "documents": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EnvelopeDocumentApiDataRequest" } } }, "required": [ "documents" ], "title": "SetEnvelopeDocumentsApiRequest" }, "SetTemplateDocumentsApiRequest": { "type": "object", "description": "`PUT \/api\/v1\/templates\/{id}\/documents`: the template's documents and their pages, replacing the\ncurrent manifest.", "properties": { "documents": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateDocumentApiData" } } }, "required": [ "documents" ], "title": "SetTemplateDocumentsApiRequest" }, "SetTemplateRolesApiRequest": { "type": "object", "description": "`PUT \/api\/v1\/templates\/{id}\/roles`: the template's roles, replacing the current list.", "properties": { "roles": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateRoleApiData" } } }, "required": [ "roles" ], "title": "SetTemplateRolesApiRequest" }, "ShowEnvelopeRequest": { "type": "object", "properties": { "expand": { "type": "array", "default": [], "items": { "type": "string" } } }, "title": "ShowEnvelopeRequest" }, "ShowTemplateRequest": { "type": "object", "properties": { "expand": { "type": "array", "default": [], "items": { "type": "string" } } }, "title": "ShowTemplateRequest" }, "SignerAuthMethod": { "type": "string", "enum": [ "none", "access_code", "sms", "email_otp" ], "title": "SignerAuthMethod" }, "SigningOrder": { "type": "string", "enum": [ "parallel", "sequential" ], "title": "SigningOrder" }, "SigningSessionApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "livemode": { "type": "boolean", "default": true }, "created": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "signing_session" } }, "required": [ "id", "url", "expires_at", "livemode", "created", "object" ], "title": "SigningSessionApiResponse" }, "TemplateApiResponse": { "type": "object", "description": "A template (`tpl_\u2026`). `documents`, `roles` and `fields` are expansions. Envelopes made from it\nkeep the template as it was then; later edits don't change them.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "name": { "type": "string" }, "workspace": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "page_count": { "type": "integer" }, "return_url": { "type": [ "string", "null" ] }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "archived": { "type": "boolean", "description": "Archived templates are hidden from lists unless `archived=true`; restore one with `POST \/templates\/{id}\/restore`" }, "share_link_enabled": { "type": "boolean", "description": "Whether the public share link is on. Its URL is returned by `POST \/templates\/{id}\/share_link`" }, "kiosk_enabled": { "type": "boolean", "description": "Whether Kiosk mode is on. Its URL is returned by `POST \/templates\/{id}\/kiosk`" }, "documents": { "anyOf": [ { "type": "object" }, { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateDocumentApiResponse" } } ] }, "fields": { "anyOf": [ { "type": "object" }, { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateFieldApiResponse" } } ] }, "roles": { "anyOf": [ { "type": "object" }, { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateRoleApiResponse" } } ] }, "object": { "type": "string", "default": "template" }, "folder": { "type": [ "string", "null" ], "description": "The template folder (`fdr_\u2026`) it is in, or null" }, "filing_rule": { "type": [ "string", "null" ], "description": "The filing rule (`frl_\u2026`) that files it, or null" } }, "required": [ "id", "created", "livemode", "name", "workspace", "metadata", "page_count", "return_url", "notification_policy", "archived", "share_link_enabled", "kiosk_enabled", "object", "folder", "filing_rule" ], "title": "TemplateApiResponse" }, "TemplateDocumentApiData": { "type": "object", "description": "One document of a template and the pages it is assembled from, in order. `visible_to` names the\nroles that see it; null (or absent) means every role.", "properties": { "name": { "type": "string", "maxLength": 255 }, "pages": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplatePageSourceApiData" } }, "visible_to": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "name", "pages" ], "title": "TemplateDocumentApiData" }, "TemplateDocumentApiResponse": { "type": "object", "description": "A document inside a template (`tdoc_\u2026`) with its page manifest. `visible_to` lists the role names\nthat see the document; null means every role.", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "template": { "type": "string" }, "position": { "type": "integer" }, "name": { "type": "string" }, "page_count": { "type": "integer" }, "form_policy": { "type": "string" }, "visible_to": { "type": [ "array", "null" ], "items": { "type": "string" } }, "pages": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplatePageApiResponse" } }, "object": { "type": "string", "default": "template_document" } }, "required": [ "id", "created", "livemode", "template", "position", "name", "page_count", "form_policy", "visible_to", "pages", "object" ], "title": "TemplateDocumentApiResponse" }, "TemplateFieldApiRequest": { "type": "object", "description": "Create (`POST`) or change (`PATCH`) a template field. Geometry is in PDF points from the top-left\nof the displayed page; `page` is within `document` and may be negative to count from the end.\nA field belongs to a signer `role`, or is a `prefill` field the sender fills in.", "properties": { "type": { "$ref": "#\/components\/schemas\/EnvelopeFieldType" }, "role": { "type": [ "string", "null" ], "maxLength": 255 }, "prefill": { "type": "boolean" }, "document": { "type": [ "string", "null" ] }, "page": { "type": "integer" }, "x": { "type": "number", "minimum": 0 }, "y": { "type": "number", "minimum": 0 }, "width": { "type": "number" }, "height": { "type": "number" }, "label": { "type": [ "string", "null" ], "pattern": "^[^.\\p{Cc}]+$", "maxLength": 255 }, "required": { "type": "boolean" }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "default_value": { "type": [ "string", "null" ], "maxLength": 5000 }, "validation": { "anyOf": [ { "$ref": "#\/components\/schemas\/FieldValidationApiDataRequest" }, { "type": "null" } ] }, "tab_order": { "type": [ "integer", "null" ], "minimum": 1 } }, "title": "TemplateFieldApiRequest" }, "TemplateFieldApiResponse": { "type": "object", "description": "A template field (`tfld_\u2026`). `box` is in PDF points from the top-left of the displayed page\n(RFC \u00a75.3.2); `page` counts within `document`, `page_number` across the template. The percent\ngeometry is the same box as a share of the page.", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "signature", "date", "text", "initials", "checkbox", "dropdown", "date_signed", "email", "name", "radio_group", "checkbox_group", "number", "attachment", "company", "title", "repeat_group" ] }, "label": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] }, "page_number": { "type": "integer" }, "box": { "type": [ "object", "null" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ] }, "x_percent": { "type": "string" }, "y_percent": { "type": "string" }, "width_percent": { "type": "string" }, "height_percent": { "type": "string" }, "default_value": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "required": { "type": "boolean" }, "is_prefill_field": { "type": "boolean" }, "validation": { "type": [ "object", "null" ], "additionalProperties": {} }, "tab_order": { "type": [ "integer", "null" ] }, "object": { "type": "string", "default": "template_field" } }, "required": [ "id", "type", "label", "role", "document", "page", "page_number", "box", "x_percent", "y_percent", "width_percent", "height_percent", "default_value", "options", "required", "is_prefill_field", "validation", "tab_order", "object" ], "title": "TemplateFieldApiResponse" }, "TemplateFormFieldApiResponse": { "type": "object", "description": "One field of a template's PDF form, as `FormFieldApiResponse` describes an envelope's, with the\n`role` that fills it. `value` is the default the form had (or the template gives it).", "properties": { "name": { "type": "string" }, "pdf_name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "signature", "date", "text", "initials", "checkbox", "dropdown", "date_signed", "email", "name", "radio_group", "checkbox_group", "number", "attachment", "company", "title", "repeat_group" ] }, "pdf_type": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] }, "page_number": { "type": "integer" }, "box": { "type": [ "object", "null" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ] }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] }, "page_number": { "type": "integer" }, "box": { "type": [ "object", "null" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ] }, "label": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] } }, "required": [ "field", "document", "page", "page_number", "box", "label", "state" ] } }, "value": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "required": { "type": "boolean" }, "read_only": { "type": "boolean" }, "status": { "type": "string", "enum": [ "assigned", "kept", "unassigned" ] }, "role": { "type": [ "string", "null" ] }, "can_keep": { "type": "boolean" }, "object": { "type": "string", "default": "template_form_field" } }, "required": [ "name", "pdf_name", "label", "type", "pdf_type", "document", "page", "page_number", "box", "widgets", "value", "options", "required", "read_only", "status", "role", "can_keep", "object" ], "title": "TemplateFormFieldApiResponse" }, "TemplateFormFieldAssignmentApiData": { "type": "object", "description": "One chosen template form field: its `name` from `GET \/templates\/{id}\/form_fields` and the role\nthat fills it. `required` and `label` change the field; left out, they stay as they are.", "properties": { "name": { "type": "string", "maxLength": 1024 }, "role": { "type": "string", "maxLength": 255 }, "required": { "type": [ "boolean", "null" ] }, "label": { "type": [ "string", "null" ], "pattern": "^[^.\\p{Cc}]+$", "maxLength": 255 } }, "required": [ "name", "role" ], "title": "TemplateFormFieldAssignmentApiData" }, "TemplateFormFieldsApiResponse": { "type": "object", "description": "The fields of a template's PDF form (`GET \/templates\/{id}\/form_fields`), one entry per form field.\n`policy` is as for envelopes. Send `acceptance_digest` back with `PUT \/templates\/{id}\/form_fields`\nso a choice made from an outdated list is refused. A signed upload or converted XFA form is\naccepted on each envelope made from the template.", "properties": { "template": { "type": "string" }, "policy": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "assigned_count": { "type": "integer" }, "acceptance_digest": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TemplateFormFieldApiResponse" } }, "object": { "type": "string", "default": "template_form_fields" } }, "required": [ "template", "policy", "count", "assigned_count", "acceptance_digest", "data", "object" ], "title": "TemplateFormFieldsApiResponse" }, "TemplateKioskApiResponse": { "type": "object", "description": "A template's Kiosk mode: a walk-up signing page for a shared device, opened at `url`. Each visitor\nsigns as `role` in a new envelope. `pin_set` says whether a staff PIN protects the device; the PIN\nitself is never returned. `url` is null while Kiosk mode is off.", "properties": { "template": { "type": "string" }, "enabled": { "type": "boolean" }, "role": { "type": [ "string", "null" ] }, "welcome_message": { "type": [ "string", "null" ] }, "pin_set": { "type": "boolean" }, "idle_timeout_seconds": { "type": [ "integer", "null" ] }, "redirect_delay_seconds": { "type": [ "integer", "null" ] }, "url": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "template_kiosk" } }, "required": [ "template", "enabled", "role", "welcome_message", "pin_set", "idle_timeout_seconds", "redirect_delay_seconds", "url", "object" ], "title": "TemplateKioskApiResponse" }, "TemplatePageApiResponse": { "type": "object", "description": "One page of a template document: where it comes from and its displayed size in points.\n`template_page` numbers pages across the whole template, the numbering `page_number` uses.", "properties": { "position": { "type": "integer" }, "template_page": { "type": "integer" }, "file": { "type": [ "string", "null" ], "description": "The uploaded file (`file_\u2026`) the page comes from, when it comes from one" }, "source_page": { "type": "integer" }, "rotation": { "type": "integer" }, "width_pt": { "type": "number" }, "height_pt": { "type": "number" } }, "required": [ "position", "template_page", "file", "source_page", "rotation", "width_pt", "height_pt" ], "title": "TemplatePageApiResponse" }, "TemplatePageSourceApiData": { "type": "object", "description": "A page for a template document: page `page` of an uploaded `file`, or of a `document` already in\nthe template.", "properties": { "page": { "type": "integer", "minimum": 1 }, "file": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "rotation": { "type": "integer", "enum": [ "0", "90", "180", "270" ], "default": 0 } }, "required": [ "page" ], "title": "TemplatePageSourceApiData" }, "TemplatePreviewApiResponse": { "type": "object", "description": "A watermarked preview of a template with each field drawn as a label. `version` is the template\nversion it shows; editing the template makes a new version, so preview again after a change.", "properties": { "template": { "type": "string" }, "version": { "type": "integer" }, "page_count": { "type": "integer" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "livemode": { "type": "boolean" }, "object": { "type": "string", "default": "template_preview" } }, "required": [ "template", "version", "page_count", "url", "expires_at", "livemode", "object" ], "title": "TemplatePreviewApiResponse" }, "TemplateRoleApiData": { "type": "object", "description": "A template role. Roles with equal `routing_order` act in parallel; higher numbers act later. An\n`access_code` role keeps its current code when `access_code` is left out. `recipient_name` and\n`recipient_email` set a fixed person that every envelope from the template gets for the role;\nsend both, or `null` for both to clear it. Left out, the role keeps its current person.", "properties": { "name": { "type": "string", "pattern": "^[^\\p{Cc}]+$", "maxLength": 255 }, "type": { "type": "string", "enum": [ "signer", "cc", "in_person_signer", "approver", "viewer" ], "default": "signer" }, "routing_order": { "type": "integer", "default": 1, "minimum": 1, "maximum": 100 }, "auth_method": { "anyOf": [ { "$ref": "#\/components\/schemas\/SignerAuthMethod" }, { "type": "null" } ] }, "access_code": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 50 }, "allow_delegation": { "type": "boolean" }, "recipient_name": { "type": [ "string", "null" ], "pattern": "^[^\\p{Cc}]+$", "maxLength": 255 }, "recipient_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 } }, "required": [ "name" ], "title": "TemplateRoleApiData" }, "TemplateRoleApiResponse": { "type": "object", "description": "A template role: the recipient an envelope made from the template gets for it. Roles with equal\n`routing_order` act in parallel; higher numbers act later. Access codes are never returned.\n`recipient_name` and `recipient_email` are the role's fixed person, or null when each envelope\nnames its own.", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "signer", "cc", "in_person_signer", "approver", "viewer" ] }, "routing_order": { "type": "integer" }, "auth_method": { "type": [ "string", "null" ] }, "has_access_code": { "type": "boolean" }, "allow_delegation": { "type": "boolean", "default": false }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_email": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "routing_order", "auth_method", "has_access_code", "allow_delegation", "recipient_name", "recipient_email" ], "title": "TemplateRoleApiResponse" }, "TemplateShareLinkApiResponse": { "type": "object", "description": "A template's public share link. Anyone with `url` can open it and sign as `role`, which creates\na new envelope from the template each time. `url` is null while the link is off.", "properties": { "template": { "type": "string" }, "enabled": { "type": "boolean" }, "role": { "type": [ "string", "null" ] }, "welcome_message": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "object": { "type": "string", "default": "template_share_link" } }, "required": [ "template", "enabled", "role", "welcome_message", "url", "object" ], "title": "TemplateShareLinkApiResponse" }, "UpdateDraftEnvelopeRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "external_id": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "send_emails": { "type": "boolean" }, "email_subject": { "type": [ "string", "null" ], "maxLength": 255 }, "email_message": { "type": [ "string", "null" ], "maxLength": 5000 }, "expires_in_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365 }, "values": { "anyOf": [ { "type": "object" }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "null" } ] } } ] }, "notification_policy": { "anyOf": [ { "type": "object" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "title": "UpdateDraftEnvelopeRequest" }, "UpdateFilingRuleApiRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "targets": { "type": "array", "description": "Replaces every destination; a status left out is no longer filed", "items": { "$ref": "#\/components\/schemas\/FilingRuleTargetApiData" } }, "is_default": { "type": "boolean" } }, "title": "UpdateFilingRuleApiRequest" }, "UpdateFolderApiRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "parent": { "type": [ "string", "null" ], "description": "Move the folder into another folder (`fdr_\u2026`) of the same type, or `null` for the top level", "pattern": "^fdr_[0-9A-HJKMNP-TV-Z]{26}$" }, "use_for_visitor_check_in": { "type": "boolean" } }, "title": "UpdateFolderApiRequest" }, "UpdateTemplateApiRequest": { "type": "object", "description": "`PATCH \/api\/v1\/templates\/{id}`: change the template's settings. Documents, roles and fields have\ntheir own endpoints.", "properties": { "name": { "type": "string", "maxLength": 255 }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "return_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "notification_policy": { "anyOf": [ { "type": "object" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "title": "UpdateTemplateApiRequest" }, "UpdateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "settings": { "type": "object", "description": "Workspace settings: `embed_allowed_origins` (origins that may frame signing pages), `signing_return_allowed_origins` (origins a hosted session's `return_url` may use, up to 50), `default_signing_window_days` (1-365), `esign_disclosure_title`, `esign_disclosure_body`, `esign_disclosure_agreement_label`. Origins only: no path, query or credentials. Only the settings sent change", "additionalProperties": {} }, "brand_kit": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } } }, "title": "UpdateWorkspaceRequest" }, "UsageRequest": { "type": "object", "properties": { "period": { "type": [ "string", "null" ] }, "workspace": { "type": [ "string", "null" ], "pattern": "^ws_[0-9A-HJKMNP-TV-Z]{26}$" }, "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "starting_after": { "type": [ "string", "null" ], "maxLength": 64 }, "ending_before": { "type": [ "string", "null" ], "maxLength": 64 } }, "required": [ "limit" ], "title": "UsageRequest" }, "VerificationMode": { "type": "string", "description": "How a public verification was asked for.\n", "enum": [ "start", "upload", "code", "hash" ], "title": "VerificationMode" }, "VerificationState": { "type": "string", "description": "What the public verification page found (RFC \u00a75.8.5).\n", "enum": [ "ready", "record_found", "not_found", "verified", "intact_timestamped", "changed", "unrecognized", "seal_missing", "voided", "unreadable", "unverifiable" ], "title": "VerificationState" }, "VerifyPublicDocumentRequest": { "type": "object", "properties": { "pdf": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "maxLength": 20480 }, "sha256": { "type": [ "string", "null" ], "pattern": "^[a-fA-F0-9]{64}$" } }, "title": "VerifyPublicDocumentRequest" }, "VoidEnvelopeRequest": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 1000 } }, "title": "VoidEnvelopeRequest" }, "WebhookDeliveryApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "event": { "type": [ "string", "null" ] }, "webhook_endpoint": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "last_status_code": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "last_response_body": { "type": [ "string", "null" ], "description": "Truncated to 5,000 characters" }, "next_attempt_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "failed_at": { "type": [ "string", "null" ] }, "attempt_log": { "type": [ "array", "null" ], "items": { "type": "string" } }, "object": { "type": "string", "default": "webhook_delivery" } }, "required": [ "id", "created", "event", "webhook_endpoint", "type", "status", "attempts", "last_status_code", "last_error", "last_response_body", "next_attempt_at", "delivered_at", "failed_at", "attempt_log", "object" ], "title": "WebhookDeliveryApiResponse" }, "WebhookEndpointApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabled_events": { "type": "array", "items": { "type": "string" } }, "include": { "type": "array", "items": { "type": "string" } }, "api_version": { "type": "string" }, "scope": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "workspace": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "secret": { "type": "string", "description": "Only present in the response that creates or rotates the secret" }, "object": { "type": "string", "default": "webhook_endpoint" } }, "required": [ "id", "created", "livemode", "url", "description", "enabled_events", "include", "api_version", "scope", "status", "metadata", "workspace", "platform", "object" ], "title": "WebhookEndpointApiResponse" }, "WorkspaceApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "settings": { "type": "object", "description": "`embed_allowed_origins`, `signing_return_allowed_origins`, `default_signing_window_days` and the signing disclosure text (`esign_disclosure_title`, `esign_disclosure_body`, `esign_disclosure_agreement_label`)", "additionalProperties": {} }, "brand_kit": { "type": [ "string", "null" ] }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "branding": { "type": "object", "additionalProperties": {} }, "platform": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "object": { "type": "string", "default": "workspace" } }, "required": [ "id", "created", "livemode", "name", "external_id", "metadata", "settings", "brand_kit", "notification_policy", "branding", "platform", "status", "object" ], "title": "WorkspaceApiResponse" }, "WorkspaceExportApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "status_url": { "type": "string" }, "download_url": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] } }, "required": [ "id", "status", "status_url", "download_url", "expires_at", "error_code", "sha256", "size_bytes" ], "title": "WorkspaceExportApiResponse" }, "WorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "external_id": { "type": [ "string", "null" ], "pattern": "\\S", "maxLength": 255 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "settings": { "type": "object", "description": "Workspace settings: `embed_allowed_origins` (origins that may frame signing pages), `signing_return_allowed_origins` (origins a hosted session's `return_url` may use, up to 50), `default_signing_window_days` (1-365), `esign_disclosure_title`, `esign_disclosure_body`, `esign_disclosure_agreement_label`. Origins only: no path, query or credentials", "default": [], "additionalProperties": {} }, "brand_kit": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] }, "notification_policy": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } } }, "required": [ "name" ], "title": "WorkspaceRequest" }, "WorkspaceUsageApiResponse": { "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string" }, "livemode": { "type": "boolean" }, "workspace": { "type": "string" }, "period": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": { "type": "integer" } }, "api_envelopes": { "anyOf": [ { "description": "The billing account's API allowance right now; null for platform-managed workspaces", "$ref": "#\/components\/schemas\/ApiEnvelopeUsageApiResponse" }, { "type": "null" } ] }, "object": { "type": "string", "default": "workspace_usage" } }, "required": [ "id", "created", "livemode", "workspace", "period", "metrics", "api_envelopes", "object" ], "title": "WorkspaceUsageApiResponse" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiErrorResponse" } } } } } } }