{"openapi": "3.1.0", "info": {"title": "Tvarka Sign API", "version": "1.30.0", "x-status": "Live and publicly reachable at https://sign-api.tvarka.pro since 2026-08-27, on both production boxes and behind Cloudflare. The first production tenant was onboarded 2026-08-28 and the launch gate ceremony ran the same day: a production signing ordered through this API was signed with a real eID (Mobile-ID) and validated QUALIFIED_VALID, and webhook delivery was exercised the same day against an external production receiver with the HMAC signature and idempotency key verified on arrival.", "description": "Machine channel for Tvarka Sign: post a document and a list of signers,\nand Tvarka runs its ordinary qualified signing ceremony for each of them.\n\n**What this API is.** Orchestration. The ceremony itself is the shipped\nTvarka Sign ceremony a person already uses: the same hosted page, the\nsame signing methods (Lithuanian ID card over NFC in the Tvarka Sign\nmobile app, Smart-ID and Mobile-ID on the hosted page), the same PIN\nrules, the same invitation lifecycle. A signature is always a human act\nwith the signer's own eID, so the orchestration endpoints are about\ngetting a document in front of the right person and finding out what\nthey did. Headless signatures (`/v1/signatures`, v1.6.0) run the same\nSmart-ID and Mobile-ID PIN sequences without the hosted page: your\napplication shows the verification code and the signer confirms on\ntheir phone.\n\n**Signature formats.** This orchestration API accepts PDF, enveloping CAdES\n(`.p7m`), ASiC-E (`.asice`, `.sce`, `.bdoc`, `.edoc`), ASiC-S\n(`.asics`, `.scs`), and the ADOC family - `.adoc`, `.bedoc`, `.cedoc`,\n`.gedoc`, `.ggedoc` - for signing an eligible container or adding a signature to an existing one.\nA container is signed in place, never converted. MDOC is not accepted\nfor countersigning: its composer writes a first signature only.\n\n**Office files and images (v1.9.0).** A document posted as\n`.docx`, `.doc`, `.odt`, `.rtf`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.odp`, `.txt`, `.jpg`, `.jpeg` and `.png` is converted to PDF/A-2b and that PDF is signed,\nin every intake: `content`, `url` and `POST /v1/files`. The signed\nfile and its name are the PDF (`Contract.docx` becomes\n`Contract.pdf`); the original is not kept. `POST /v1/conversions`\nreturns the PDF without signing. Conversion costs nothing extra.\nThe complete Tvarka API estate produces every\nRegulation (EU) 2026/248 Annex I family: PAdES, XAdES, CAdES, JAdES and\nASiC. The ATK API is the lower-level card and reader API, including full\nLT ATK NFC, USB/reader and detached CAdES support. The DD API produces\nJAdES. See the format matrix in the developer guide before selecting a\nsurface.\n\n**Signature validation.** Tvarka provides advisory signature\nvalidation results for integration into your document workflows.\n\n**Tenancy and billing.** A tenant is a Tvarka entity with a Sign\nworkspace, and ceremonies are raised in that entity's name, so the\ncounterparty sees who is actually asking. Signatures are billed to that\nworkspace at the flat prices of Tvarka Sign; there is no separate API\ntariff and no subscription.\n\n**Sandbox.** A `tsk_test_` key opens real ceremonies but is exempt from\nthe funding precondition, and can drive a signing to `completed`,\n`declined` or `expired` through `/simulate`. A simulated completion is\nexplicitly marked `sandbox_simulation` and returns a real downloadable\nartifact, so download, hashing and storage can be exercised without a\nreal eID. The sandbox never adds a signature: an unsigned PDF comes back\nas the caller's own pages with a banner saying it is not signed, and\nanything posted already signed comes back byte-identical. Every artifact\nis flagged `sandbox: true`. Production ceremonies produce real qualified electronic signatures. A\nproduction completion is always a real human ceremony.\n\n**Custom PDF stamps (v1.4.0).** Exact PDF placement is included for\nevery workspace, in Tvarka Sign and this API (v1.13.1). A company logo\nis a premium entitlement that Tvarka activates. VIP whitelabel is a\nseparate premium entitlement for custom or omitted vendor text; standard clients\nkeep the default Tvarka line and do not see the text controls.\nAn active company Vadovas configures the logo and previews the appearance\nin the cloud browser at https://sign.tvarka.pro/sign/app/users/?tab=stamp\n(Users and access -> Parašo išvaizda). Controls stay visible but disabled\nuntil activation. Operators grant both SKUs in Administravimas -> Parašo\nišvaizda. This contract exposes no branding upload, text-edit or\nentitlement-management endpoints; do not send those fields in API requests.\n\nPNG logos: up to 1 MB, longest side 200-2000 px, neither side above 2000 px,\naspect ratio 1:3 to 3:1. Transparency is retained and scaling is proportional.\nVIP vendor text: default, custom (up to 32 printable characters that fit),\nor omitted. Signer identity, time and purpose stay visible.\n\nSet per-signer `visibleSignature` on create, add-signer or batch requests;\nMCP `request_signatures` accepts the same shape for a vault document.\nUse exactly one of `{\"page\":1,\"x\":36,\"y\":36,\"width\":148,\"height\":52}`\nor `{\"field\":\"Sig_Vadovas\"}`. Batch placements must work on every document\nbefore invitations are dispatched. Accepted normalized placement is\nimmutable and returned in signer status. Omission keeps corner/cascade\nplacement with workspace branding. Explicit boxes never silently move;\ncallers must avoid overlaps. PDF signers only, not viewers or containers.\n\nAn API order snapshots branding on acceptance, including later signers,\nretries and idempotent replays. Workspace edits, reset or entitlement\nrevocation do not alter accepted snapshots. New snapshots after VIP\nrevocation use the\ndefault vendor line. Regular Sign uses the same branding but a separate\ndocument snapshot and its own per-user Mano parašo vieta editor; that\neditor does not change API-owned placement. Internal electronic signatures\nkeep their non-qualified label and original overlay position.\n\nSandbox completion previews the requested placements and branding on\nunsigned PDFs, including default-corner signers and MCP vault orders.\nAlready-signed input remains byte-identical and receives no stamp preview.\n`400 validation-failed` names invalid input with JSON pointers;\n`422 stamp-preparation-failed` means sandbox preview preparation failed.\nPlacement and snapshotted logo are revalidated against the locked revision\nduring real signing. A stamp preparation failure makes signer and order\nterminally failed, emits `signing.signer_failed` and `signing.failed`, and\nretracts remaining invitations and pending work while preserving collected\nsignatures. Provider outages alone do not trigger stamp-failure cleanup.\nFull guide: https://sign-api.tvarka.pro/docs#stamps\n\n**Headless signatures (v1.6.0).** `POST /v1/signatures` signs one\ndocument for one signer with Smart-ID or Mobile-ID, with no hosted page,\nno invitation and no email. Your application shows the verification\ncode; the signer confirms on their phone. The PIN sequences are the ones\nthe hosted ceremony runs, unchanged: when Tvarka already knows the\nsigner's signing certificate, one confirmation signs. A configured\ncertificate service can obtain it without a PIN, so first use can also\nneed only the signing PIN. Certificate-capture fallback can require an\nidentity confirmation first, then signing (at most two PINs). Follow\nthe current verification code when `step` moves from\n`authentication` to `signing`, and a `signature.confirmation_required`\nwebhook carries the new code. Which sequence runs is Tvarka's\ndecision, not the caller's. One request signs one document; for many\ndocuments at once, the ATK API signs in bulk with the ID card.\n\nProfiles are named, never free parameters: `cades-detached` signs your\nSHA-256 hash and returns a detached `.p7s` at CAdES-BASELINE-LT (the\ntimestamp, the certificate chains and fresh revocation data are embedded,\nso it validates without online lookups); `pades` signs a PDF, such as the PDF/A-2 that ESPBI renders, and\nreturns it signed at PAdES-BASELINE-LT, added as an incremental update, so\nthe document and any earlier signature or timestamp stay intact;\n`cades-enveloping` (v1.20.0) signs a PDF and returns it inside the\nsignature, as a `.pdf.p7m` (`application/pkcs7-mime`) at\nCAdES-BASELINE-LT. Since v1.21.0 a whole file goes in `document.file`\nfor five more profiles: `xades-enveloped` signs an XML document and\nreturns it with the signature inside, at XAdES-BASELINE-LT, as\ne-invoices and XML filings carry it; `cades-enveloping-xml` returns the\nXML inside the signature, as an `.xml.p7m` at CAdES-BASELINE-LT;\n`asice` and `edoc` put any file in an ASiC-E container at\nXAdES-BASELINE-LT, named `.asice` or the Latvian `.edoc`; `jades` signs\na JSON payload and returns a JAdES-BASELINE-LT signature in the JWS JSON\nserialization with the payload attached (`application/jose+json`). An\nXML that already carries a signature is refused by `xades-enveloped`.\n`jades` needs an RSA or P-256 signing key; any other key ends the\nsignature as `certificate_not_qualified` before the phone is asked. A `pades`\nsignature carries a visible stamp when you ask for it (v1.13.0), under\nthe same rules as Tvarka Sign: the signer's name from the signing\ncertificate and the signing time, with the workspace logo where the\nworkspace has one. `\"visibleSignature\": true` puts it in the default\ncorner; an object places it at exact coordinates or in an existing empty\nfield. Without it the signature stays invisible. The stamp speaks the language of the company's country;\na company outside Lithuania gets the Tvarka.eu stamp. `renderHash` is required: the digest of what you\nshowed the signer, kept as evidence beside `display.text`, the input\ndigest, the verification codes and the signing certificate. You are\nresponsible for what you display.\n\nEvery production key signs headless at once, and so does every sandbox\nkey. A signature is billed once, on success, as one remote signature\nat the flat price of Tvarka Sign. Declined, expired, failed and\ncancelled signatures are free, and a completion that arrives after a\ncancellation is discarded unbilled. The sandbox never reaches the\nsigner's phone and never adds a signature: `/simulate` drives the\noutcome. Signed documents are kept for 30 days or until\n`/v1/erasure`; the evidence record stays.\n\n**Simple e-signatures (v1.11.0).** `level: \"esign\"` on\n`POST /v1/signings` (and on MCP `send_document` and\n`request_signatures`) asks for a simple electronic signature instead of\na qualified one. Each signer reads the PDF and signs on the Tvarka page\nwith the same ceremony the Tvarka Sign app uses; no eID is needed. One\nPDF per signing (Office files and images are converted first), one or\nmore signers, parallel or sequential, `link` or `email` delivery. Each\nsigner can have one `authentication`: `email_link` (default),\n`access_code` (a code you give the signer yourself; stored only as a\nhash, never returned, logged or sent in webhooks) or `sms` (when SMS\ncodes are switched on for the workspace, else `422\nauthentication-unavailable`). The signers are fixed when the signing is\ncreated: add, change and remove answer `409 roster-locked`; cancel and\ncreate a new signing instead. Fields only a qualified signing takes\n(`personalCode`, `methods`, `visibleSignature`, `signingPurpose`,\n`role`) are refused by name, and `authentication` is refused on a\nqualified signing. Omitting `level` keeps `qualified`, so existing\nclients see no change. When simple e-signatures are not switched on for\nthe API, an explicit `esign` answers `403 esign-not-enabled`; it never\nbecomes a qualified signing.\n\nOnce every signer has signed, Tvarka seals the file with a document\ntimestamp and records the evidence; until then the signing stays\n`pending` with `processingStage: finalizing`. It completes only when the\nsealed file, the evidence and the one charge are recorded. A timestamp\noutage delays this; it never asks anyone to sign again or charges twice.\n`GET /v1/signings/{signingId}/document` then returns the sealed PDF, and\n`GET /v1/signings/{signingId}/evidence` returns the evidence ZIP: the\nsealed PDF, the separate summary when the file could not take one, and\nevery signing event's timestamp token. The signing summary inside shows\neach signer's name, masked email, method, time and IP address. The\ncompleted signing\nnames its `evidence.referenceCode` and public `verificationUrl`; a\nqualified-signature validator does not apply (`validation:\nnotApplicable`). Billed once per completed document, however many\nsigners, at the workspace's e-signature price; declined, expired,\ncancelled and unfinished signings are free. Archiving refuses a simple\ne-signature (`409 level-not-supported`). After signing, each signer gets\na copy of the completed file by email, as in the Tvarka Sign app. A\nsimple e-signature can send the signer back to a registered `returnUrl`\nafter signing, as a qualified signing does (v1.29.0). Once every signer has signed, the signing can no longer be\ncancelled (`409 signing-finalizing`). Through MCP, a vault document that\nis already out for signing is refused (`409 document-in-signing`).\n\n**Headless signing providers (v1.11.0).** Tvarka signs headless\nSmart-ID and Mobile-ID through SK ID Solutions directly or through its\nother provider, and may take the signing certificate from SK with no\naction from the signer. The contract does not change with the route:\nthe same `verificationCode`, steps, profiles, results and price. Every\nsignature now carries `nextAction`: `compare_code` (show\n`verificationCode`), `confirm_certificate` (the signer confirms their\nSmart-ID account in the app, no PIN), `scan_qr`, `open_app`, `wait` or\n`none`, with a `revision` that grows with every step; the\n`signature.confirmation_required` webhook carries the same object.\nWhen in doubt, poll. A start that may have reached the phone without an\nanswer is never repeated: the signature fails as `initiation_unknown`\n(not billed); ask the signer to dismiss any prompt and retry after two\nminutes.\n\n`interaction: {\"type\": \"qr\"}` or `{\"type\": \"app_link\"}` signs with\nSmart-ID by QR code or app link (when switched on for the API, else\n`422 interaction-unavailable`). No personal code is needed: whoever\npicks the Smart-ID account signs, and the result names them. Send an\noptional `signer.personalCode` to accept only that person. An Estonian\ncode is taken here too, read as for a hosted signer (v1.27.2).\nShow `nextAction.qrLink` as a QR code and fetch a fresh one every second\n(`refreshAfterSeconds`; Smart-ID requires a new code each second).\n`app_link` needs a `returnUrl` registered for this API client and a\n`returnState`; after signing, the Smart-ID app returns the signer through\nTvarka to `returnUrl?state=<returnState>&signatureId=<id>`. Check that\n`state` belongs to the browser session that started the signing; the\nresult itself comes only from polling or the webhook.\n\n**Automation platforms (v1.12.0).** `POST /v1/webhooks` registers a\ncallback URL for the events you choose, for every signing this\nintegration creates: the way Zapier, Make and Power Automate turn a\ntrigger on. `DELETE /v1/webhooks/{webhookId}` turns it off.\nRegistering the same URL again replaces its events. A delivery carries\nthe event, its `eventId` (the `X-Tvarka-Idempotency-Key` value), the\n`webhookId` and the whole `signing` as `GET /v1/signings/{signingId}`\nshows it, without ceremony links. It is signed and retried like a\n`webhookUrl` delivery, and a `410 Gone` answer removes the\nsubscription. A signing's own `webhookUrl` keeps working beside it.\n`GET /v1/me` names the workspace and environment the key acts for.\n`GET /v1/signings` filters by `externalId`. REST and MCP also accept\nthe key as `X-Api-Key: <key>`, for platforms that send a key exactly\nas typed.\n\n**Templates and bulk send (v1.14.0).** A template is a saved PDF with\nits signer roles, signature level, order and, per role, the\n`visibleSignature` placement. `POST /v1/templates` saves one; the\nTvarka Sign app saves them too, and both doors see the workspace's\ntemplates. `POST /v1/signings` with `templateId` sends it: name each\nrole in `templateRoles` with an email, and leave out a role that has a\nsaved signer. The document, level and order come from the template.\nA role's saved box is checked by the sizes of the template's level, the\nsizes the Tvarka Sign app saves it with (v1.14.1). A box sent in a\nrequest keeps the 148 x 52 pt minimum.\n`POST /v1/templates/{templateId}/bulk-sends` sends one signing per row,\nup to 500 rows checked whole before anything is created, and\n`GET /v1/bulk-sends/{bulkSendId}` follows it. Each row is an ordinary\nsigning with its own webhooks and the ordinary price.\n\n**Tvarka Formos (v1.16.0).** A form request asks one person to fill\none or more published form templates and sign them once, as one\ndocument, with a qualified signature (Smart-ID or Mobile-ID).\n`GET /v1/form-templates` lists the workspace's published template\nversions with their fields, each under its semantic identifier, and\neach with its legal basis. `POST /v1/form-requests` creates a request\nwith the person's phone or email, the visit time and prefill by\nsemantic identifier. The link goes out three days before the visit by\ndefault, or at `sendAt`, or at once with `sendNow`; one reminder goes\nout a day before the visit; the request expires a day after it.\n`GET /v1/form-requests/{formRequestId}` returns the status, the events\nand, once submitted, the values. `PATCH` moves the visit, resends the\nlink or cancels. The signed PDF, an evidence ZIP and the attachments\nhave their own routes. Webhooks `form_request.*` reach the request's\n`webhookUrl` and the workspace's webhook subscriptions. A completed\nrequest is charged as one e-signature document; the qualified signature\nand SMS codes are charged as on any signing. Kiosk requests open with\nthe Tvarka kiosk.\n\n**Compatibility.** Ignore unknown response properties. Requests reject\nunknown fields. Additive response fields may arrive in minor releases;\nremovals and incompatible changes require a new major API contract.\n\n**Limits and recovery.** Documents support up to 100 MB (100,000,000 bytes)\nthrough multipart POST /v1/files and document.fileToken. Inline base64\nremains limited to 15 MiB decoded; the JSON envelope is limited to 21 MiB.\nEach batch also caps combined source bytes and combined prepared bytes\nseparately at 100,000,000 bytes, counting repeated file tokens repeatedly.\nMCP accepts identifiers, not uploads, and limits requests to 64 KiB.\nInitial invitation email is queued durably; emailStatus reports backend\nacceptance rather than inbox delivery. Webhooks retry transport errors,\n3xx, 401, 403, 404, 408, 425, 429 and 5xx for up to 72 hours with capped\nexponential backoff; other refusals are terminal. Redirects are never\nfollowed. Deliveries may repeat or arrive out of order: deduplicate by\nX-Tvarka-Idempotency-Key. Exhausted retained events can be replayed by\nsupport with the same immutable body and deduplication key. The receiver\nshould acknowledge promptly (10-second HTTP timeout). Preflight 4xx\ncreate refusals before resource creation release the Idempotency-Key;\nretry the identical request after correcting funding or throttling.\nA callback lookup timeout, exhausted resolver capacity or temporary DNS\nfailure before resource creation returns 503 callback-resolution-unavailable\nwith Retry-After and also permits retry with the same key. Invalid callback\nsyntax, non-existent hosts and private addresses remain validation failures.\nAmbiguous executions retain the key and are never automatically rerun.\n", "contact": {"name": "Tvarka", "email": "info@tvarka.pro", "url": "https://tvarka.pro"}}, "servers": [{"url": "https://sign-api.tvarka.pro", "description": "Production and sandbox (selected by the key)"}], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}, {"agentOAuth": ["sign.read", "sign.signings"]}], "tags": [{"name": "Signings", "description": "Create and follow a signing."}, {"name": "Webhooks", "description": "Callback URLs for automation platforms."}, {"name": "Account", "description": "Who the key acts for."}, {"name": "Batches", "description": "Group independent signings."}, {"name": "Templates", "description": "Saved documents with signer roles, sent again in one call or to a list."}, {"name": "Kiosks", "description": "Tablets at the desk, where a person signs by hand."}, {"name": "Files", "description": "Reusable uploads retained for seven days."}, {"name": "Signatures", "description": "Headless Smart-ID and Mobile-ID signing of one document."}, {"name": "Forms", "description": "Tvarka Formos. Forms filled on the person's own phone and signed once."}], "paths": {"/v1/signings": {"get": {"tags": ["Signings"], "operationId": "listSignings", "summary": "List signings", "parameters": [{"name": "status", "in": "query", "schema": {"$ref": "#/components/schemas/SigningStatus"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "startingAfter", "in": "query", "schema": {"type": "string", "format": "uuid"}}, {"name": "externalId", "in": "query", "description": "Only signings created with this `externalId` (v1.12.0).", "schema": {"type": "string", "maxLength": 120}}], "responses": {"409": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "A newest-first page ordered by creation time then UUID, both descending.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SigningList"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}}}, "post": {"tags": ["Signings"], "operationId": "createSigning", "summary": "Create a signing", "description": "Stores the document, opens one ceremony per signer, and returns the\nceremony URLs (or emails them, with `delivery: email`).\n`level: esign` asks for a simple e-signature (v1.11.0); see the\ndescription above.\n\nAll signers sign the same document and are unordered: whoever opens\ntheir link first signs first, and each subsequent signer signs the\noutput the previous one produced. Two signers never sign at the same\nmoment - the ceremony serializes them.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateSigningRequest"}}}}, "responses": {"413": {"$ref": "#/components/responses/Problem"}, "409": {"description": "The idempotency key conflicts, is pending, or has an erased or expired result.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "201": {"description": "The signing was created and every signer has a live ceremony.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signing"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"description": "The tenant cannot pay for the ceremony: no payment rail, an\noverdue invoice, or a tripped usage ceiling. Nothing was\ncreated and nobody was invited. `recoveryUrl` names the web\npage where the tenant can fix it.\n", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "403": {"$ref": "#/components/responses/Problem"}, "422": {"description": "A document that cannot take the requested signature returns\n`document-not-signable` with `final: true` and a stable\n`errors[].code`. Retrying the same file and method cannot succeed. Not billed.\n", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}, "examples": {"detachedSignature": {"value": {"type": "https://tvarka.pro/problems/sign-api/document-not-signable", "title": "The document cannot be signed.", "status": 422, "final": true, "errors": [{"pointer": "/document", "code": "SIGN_DETACHED_CADES_SIGNING_BLOCKED", "detail": "A detached signature holds no document to sign. Post the signed document itself."}]}}}}}}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signings/{signingId}": {"get": {"tags": ["Signings"], "operationId": "getSigning", "summary": "Get a signing", "description": "Current state of the signing and each of its signers.", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "responses": {"409": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The signing.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signing"}}}}, "404": {"$ref": "#/components/responses/Problem"}}}, "patch": {"tags": ["Signings"], "operationId": "updateSigning", "summary": "Update a live signing deadline", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"expiresInDays": {"type": "integer", "minimum": 1, "maximum": 30}}, "required": ["expiresInDays"], "additionalProperties": false}}}}, "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The updated signing.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signing"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}}}, "delete": {"tags": ["Signings"], "operationId": "eraseSigning", "summary": "Erase one signing", "description": "Cancels a live signing first, then purges captured identity and\ncaller-supplied personal data. For a document uploaded through this\nAPI, its bytes and vault record are also deleted. If the MCP server\nopened the ceremony on a pre-existing vault document, that shared\ndocument and its bytes are preserved while the dedicated ceremony is\nremoved. A de-identified audit row remains. Idempotent.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Erasure result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"signingId": {"type": "string", "format": "uuid"}, "deleted": {"type": "boolean", "const": true}, "changed": {"type": "boolean"}}, "required": ["signingId", "deleted", "changed"]}}}}, "404": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/batches": {"post": {"tags": ["Batches"], "operationId": "createBatch", "summary": "Raise one signing per document for one set of parties", "description": "Batch operations group documents for coordinated creation and status\ntracking, with one API call and one batch identifier. Each document\nfollows its own signing ceremony and receives its own signature.\nSigners complete the authentication and signing steps for each document.\n\nCreation is atomic: either every signing in the batch is raised, or\nthe error response means none was.\nCombined source bytes and combined prepared bytes each have a\n100,000,000-byte limit, including repeated uses of the same file token.\nKnown oversized inputs are refused before stored-file reads; remote\ndownloads and stored-file reads use the remaining byte allowance.\nAggregate overflow returns 413. A remote-download refusal returns\n400 with the document URL pointer. Flattening complexity and its\ncooperative processing budget are shared across all batch documents.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 255}, "documents": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "object", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}, "fileToken": {"type": "string", "format": "uuid"}, "flatten": {"type": "boolean"}}, "required": ["name"], "additionalProperties": false}}, "signers": {"type": "array", "minItems": 1, "items": {"$ref": "#/components/schemas/SignerRequest"}}, "delivery": {"type": "string", "enum": ["link", "email"]}, "signingOrder": {"type": "string", "enum": ["parallel", "sequential"]}, "returnUrl": {"type": "string", "format": "uri", "maxLength": 500, "description": "Exact registered HTTPS return URL; requires returnState."}, "returnState": {"type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$"}, "embedOrigin": {"type": "string", "format": "uri", "maxLength": 255, "description": "Exact registered HTTPS origin (https://host[:port]) allowed to embed the ceremony in an iframe (v1.29.0)."}, "webhookUrl": {"type": "string", "format": "uri"}, "externalId": {"type": "string", "maxLength": 120}, "expiresInDays": {"type": "integer", "minimum": 1}, "softDeadlineInDays": {"type": "integer", "minimum": 1, "description": "Applied to every signing the batch raises."}}, "required": ["title", "documents", "signers"], "additionalProperties": false}}}}, "responses": {"403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "422": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "409": {"description": "The idempotency key conflicts, is pending, or has an erased or expired result.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The batch and every signing it raised.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Batch"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}}}}, "/v1/batches/{batchId}": {"get": {"tags": ["Batches"], "operationId": "getBatch", "summary": "Poll a batch and every signing in it", "parameters": [{"$ref": "#/components/parameters/BatchId"}], "responses": {"409": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The batch.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Batch"}}}}, "404": {"$ref": "#/components/responses/Problem"}}}}, "/v1/templates": {"get": {"tags": ["Templates"], "operationId": "listTemplates", "summary": "List the workspace's templates", "description": "Newest first, at most 200 (v1.14.0).", "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The templates.", "content": {"application/json": {"schema": {"type": "object", "properties": {"templates": {"type": "array", "items": {"$ref": "#/components/schemas/Template"}}}}}}}}}, "post": {"tags": ["Templates"], "operationId": "createTemplate", "summary": "Save a template", "description": "Saves a copy of one unsigned PDF with its roles (v1.14.0). The\ndocument takes the signing intake (`content`, `fileToken`, `url`,\n`markdown`; Office files and images are converted to PDF). A role's\n`visibleSignature` is checked against the PDF now. A role with an\n`email` has a saved signer, who is invited on every send unless the\nsend names the role with another person.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateTemplateRequest"}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The saved template.", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}, "description": "The template's URL."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Template"}}}}}}}, "/v1/templates/{templateId}": {"get": {"tags": ["Templates"], "operationId": "getTemplate", "summary": "Get a template", "parameters": [{"$ref": "#/components/parameters/TemplateId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The template.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Template"}}}}}}, "delete": {"tags": ["Templates"], "operationId": "deleteTemplate", "summary": "Delete a template", "description": "The template's author or a company administrator deletes it.\nSignings already sent from it keep their own documents (v1.14.0).\n", "parameters": [{"$ref": "#/components/parameters/TemplateId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "204": {"description": "Deleted."}}}}, "/v1/templates/{templateId}/bulk-sends": {"post": {"tags": ["Templates"], "operationId": "createBulkSend", "summary": "Send a template to a list, one signing per row", "description": "Every row is checked first, exactly as a single send from the\ntemplate would be; one bad row refuses the list and nothing is\ncreated. Then the rows are sent in the background (v1.14.0). A row\nmay not carry `personalCode` or an `access_code` authentication:\nthose signings are sent one by one. A simple e-signature list must\nfit today's invitation allowance in full (429 `invitation-limit`).\n", "parameters": [{"$ref": "#/components/parameters/TemplateId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateBulkSendRequest"}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "202": {"description": "The list is accepted and queued.", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}, "description": "The bulk send's URL."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkSend"}}}}}}}, "/v1/bulk-sends/{bulkSendId}": {"get": {"tags": ["Templates"], "operationId": "getBulkSend", "summary": "Follow a list", "parameters": [{"$ref": "#/components/parameters/BulkSendId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The list's progress, with one entry per row sent so far.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkSend"}}}}}}}, "/v1/form-templates": {"get": {"tags": ["Forms"], "operationId": "listFormTemplates", "summary": "List the published form templates", "description": "The newest published version of each of the workspace's own form\ntemplates and of each statutory template it adopted, with the fields\na request can prefill (v1.16.0).\n", "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The published template versions.", "content": {"application/json": {"schema": {"type": "object", "properties": {"formTemplates": {"type": "array", "items": {"$ref": "#/components/schemas/FormTemplateVersion"}}}}}}}}}}, "/v1/form-requests": {"get": {"tags": ["Forms"], "operationId": "listFormRequests", "summary": "Read the workspace's form requests", "description": "The requests of the workspace, the latest change last (v1.18.0). A\nsystem that cannot receive webhooks, such as a hospital system behind\na firewall, asks again with the `updatedSince` given in `next`.\n", "parameters": [{"name": "externalId", "in": "query", "schema": {"type": "string"}}, {"name": "status", "in": "query", "schema": {"$ref": "#/components/schemas/FormRequestStatus"}}, {"name": "updatedSince", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 100}}], "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The requests.", "content": {"application/json": {"schema": {"type": "object", "properties": {"formRequests": {"type": "array", "items": {"allOf": [{"$ref": "#/components/schemas/FormRequest"}, {"type": "object", "properties": {"updatedAt": {"type": "string", "format": "date-time"}}}]}}, "next": {"type": ["object", "null"], "properties": {"updatedSince": {"type": "string", "format": "date-time"}}}}}}}}}}, "post": {"tags": ["Forms"], "operationId": "createFormRequest", "summary": "Ask a person to fill and sign forms", "description": "One request holds one or more published template versions, filled in\none journey and signed once (v1.16.0). Give `respondent.phone` (the\nlink and the code go by SMS) or `respondent.email`. `prefill` is keyed\nby the fields' semantic identifiers. When `personalCode` is given,\nonly that person's qualified signature is accepted.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateFormRequest"}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "422": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The request.", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}, "description": "The request's URL."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FormRequest"}}}}}}}, "/v1/form-requests/{formRequestId}": {"get": {"tags": ["Forms"], "operationId": "getFormRequest", "summary": "Get a form request", "parameters": [{"$ref": "#/components/parameters/FormRequestId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The request, its events and, once submitted, its values.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FormRequest"}}}}}}, "patch": {"tags": ["Forms"], "operationId": "updateFormRequest", "summary": "Move, resend or cancel a form request", "description": "`visitAt` moves the visit, and with it the send time of a request not\nyet sent and the expiry. `resend: true` sends the same link again.\n`cancel: true` cancels. Nothing here makes a second submission.\n", "parameters": [{"$ref": "#/components/parameters/FormRequestId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UpdateFormRequest"}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The request after the change.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FormRequest"}}}}}}}, "/v1/form-requests/{formRequestId}/document": {"get": {"tags": ["Forms"], "operationId": "downloadFormRequestDocument", "summary": "Download the signed document", "parameters": [{"$ref": "#/components/parameters/FormRequestId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The signed PDF.", "headers": {"X-Tvarka-Document-Sha256": {"schema": {"type": "string"}}}, "content": {"application/pdf": {"schema": {"type": "string", "format": "binary"}}}}}}}, "/v1/form-requests/{formRequestId}/evidence": {"get": {"tags": ["Forms"], "operationId": "downloadFormRequestEvidence", "summary": "Download the evidence ZIP", "description": "The signed PDF, the values and the request's events.", "parameters": [{"$ref": "#/components/parameters/FormRequestId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The evidence ZIP.", "content": {"application/zip": {"schema": {"type": "string", "format": "binary"}}}}}}}, "/v1/form-requests/{formRequestId}/attachments": {"get": {"tags": ["Forms"], "operationId": "listFormRequestAttachments", "summary": "List or download the attachments", "description": "Without `attachmentId` the list; with it, that file.", "parameters": [{"$ref": "#/components/parameters/FormRequestId"}, {"name": "attachmentId", "in": "query", "required": false, "schema": {"type": "string", "format": "uuid"}}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The attachments, or one attachment's file.", "content": {"application/json": {"schema": {"type": "object", "properties": {"attachments": {"type": "array", "items": {"$ref": "#/components/schemas/FormAttachment"}}}}}, "application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}}}}}, "/v1/kiosks": {"get": {"tags": ["Kiosks"], "operationId": "listKiosks", "summary": "List the workspace's tablets", "description": "The tablets registered as kiosks in the workspace, with whether each\nis paired, online and busy (v1.15.0). A person signs on a kiosk by\nhand, at the desk; the document gets a drawn e-signature, sealed pen\ndata and a qualified document timestamp.\n", "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The kiosks.", "content": {"application/json": {"schema": {"type": "object", "properties": {"kiosks": {"type": "array", "items": {"$ref": "#/components/schemas/Kiosk"}}}}}}}}}}, "/v1/kiosk-sessions": {"post": {"tags": ["Kiosks"], "operationId": "createKioskSession", "summary": "Send a PDF to a tablet", "description": "Sends one PDF to a kiosk for a drawn e-signature (v1.15.0). The\ndocument takes the signing intake (`content`, `fileToken`, `url`,\n`markdown`). No link is mailed; the person signs on the tablet.\n`identity: sms` sends a one-time code to `signer.phone` and checks it\non the tablet before signing. A busy kiosk answers 409.\n\n`product: forms` with `formRequestId` sends a Tvarka Formos request\nto the kiosk instead (v1.17.0). The person fills the form on the\ntablet, with each field in its place on the document page, reviews\nit and signs it there by hand. A template with a staff signature\nplace, such as the doctor's, is signed by the staff member next, on\nthe same tablet. `title`, `document`, `signer` and `identity` are not\nused then. A request already on a kiosk answers with that session.\n`assisted: true` starts in assisted mode.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateKioskSessionRequest"}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The kiosk session, waiting for the tablet.", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}, "description": "The kiosk session's URL."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KioskSession"}}}}}}}, "/v1/kiosk-sessions/{kioskSessionId}": {"get": {"tags": ["Kiosks"], "operationId": "getKioskSession", "summary": "Read a kiosk session", "parameters": [{"$ref": "#/components/parameters/KioskSessionId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The kiosk session.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KioskSession"}}}}}}, "patch": {"tags": ["Kiosks"], "operationId": "updateKioskSession", "summary": "Assisted mode on or off, or cancel", "description": "`assisted: true` lets a staff member fill fields from a computer while\nthe tablet shows them; the signature waits until `assisted: false`.\n`status: cancelled` ends the session and withdraws the document from\nthe tablet.\n", "parameters": [{"$ref": "#/components/parameters/KioskSessionId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"assisted": {"type": "boolean"}, "status": {"type": "string", "enum": ["cancelled"]}}, "additionalProperties": false}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The kiosk session.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KioskSession"}}}}}}}, "/v1/kiosk-sessions/{kioskSessionId}/document": {"get": {"tags": ["Kiosks"], "operationId": "downloadKioskDocument", "summary": "Download the signed PDF", "description": "The completed document with its signing summary and document timestamp. 409 before completion.", "parameters": [{"$ref": "#/components/parameters/KioskSessionId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The signed PDF.", "content": {"application/pdf": {"schema": {"type": "string", "format": "binary"}}}}}}}, "/v1/signings/{signingId}/archive": {"post": {"tags": ["Signings"], "operationId": "archiveSigning", "summary": "Raise the signed output to a long-term level", "description": "PDF goes PAdES-B-T to B-LT, ASiC-E goes XAdES-T to XAdES-LT: the\ncertificate chain and fresh revocation evidence are embedded so the\nsignature can still be validated once the signing certificate has\nexpired.\n\nADOC is refused by name. ADOC-V1.0 specifies XAdES-T and its\nvalidators expect that level, so \"upgrading\" one would be a\nconformance risk dressed as a favour.\n\nAlready-archived output comes back unchanged with `upgraded: false`,\nso calling this twice costs a parse and not a second signature. The\npre-archive version is kept - an upgrade adds a version, never\nreplaces one.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "responses": {"400": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The level now held, and whether this call raised it.", "content": {"application/json": {"schema": {"type": "object", "properties": {"signingId": {"type": "string", "format": "uuid"}, "level": {"type": "string", "example": "PAdES-B-LT"}, "upgraded": {"type": "boolean"}, "document": {"$ref": "#/components/schemas/SignedDocument"}}}}}}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "422": {"$ref": "#/components/responses/Problem"}}}}, "/v1/files": {"post": {"tags": ["Files"], "operationId": "uploadFile", "summary": "Store a document once for reuse across signings", "description": "Returns a `fileToken` a later signing may reference instead of\ncarrying base64 again. Multipart accepts one binary part named file,\nup to 100,000,000 bytes; JSON accepts up to 15 MiB decoded. Format\nvalidation is identical for both transports. Office files and\nimages are converted to PDF/A-2b on upload (v1.9.0), so the stored\nfile and its `name` are the PDF.\n\nThe bytes are **copied** into each signing that uses the token, never\nshared by reference: deleting a file, or letting it expire, can never\nreach backwards into a signing that already used it.\n", "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "required": ["file"], "additionalProperties": false, "properties": {"file": {"type": "string", "format": "binary", "description": "One document, at most 100,000,000 bytes. Preserve its filename extension."}}}}, "application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}}, "required": ["name", "content"], "additionalProperties": false}}}}, "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "422": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The stored file.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredFile"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}}}}, "/v1/conversions": {"post": {"tags": ["Files"], "operationId": "convertDocument", "summary": "Convert an Office file or image to PDF/A-2b", "description": "Returns the PDF/A-2b bytes of one `.docx`, `.doc`, `.odt`, `.rtf`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.odp`, `.txt`, `.jpg`, `.jpeg` and `.png` file, ready to sign\nlocally or to post as a document. Nothing is stored and nothing is\nbilled. Multipart accepts one binary part named file, up to\n100,000,000 bytes; JSON accepts up to 15 MiB decoded. Added in\nv1.9.0.\n", "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "required": ["file"], "additionalProperties": false, "properties": {"file": {"type": "string", "format": "binary", "description": "One file, at most 100,000,000 bytes. Its extension selects the converter."}}}}, "application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}}, "required": ["name", "content"], "additionalProperties": false}}}}, "responses": {"200": {"description": "The converted PDF/A-2b, as an attachment named after the source file with a `.pdf` extension.", "content": {"application/pdf": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "422": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/files/{fileToken}": {"get": {"tags": ["Files"], "operationId": "getFile", "summary": "Inspect a stored file", "parameters": [{"$ref": "#/components/parameters/FileToken"}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The stored file.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredFile"}}}}, "404": {"$ref": "#/components/responses/Problem"}}}, "delete": {"tags": ["Files"], "operationId": "deleteFile", "summary": "Purge a stored file", "description": "Drops the bytes. Signings that already referenced the token are\nuntouched, because they hold their own copy.\n", "parameters": [{"$ref": "#/components/parameters/FileToken"}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The file, now purged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredFile"}}}}, "404": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signings/{signingId}/comments": {"get": {"tags": ["Signings"], "operationId": "listComments", "summary": "Read the notes on a signing", "parameters": [{"$ref": "#/components/parameters/SigningId"}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "startingAfter", "in": "query", "description": "Comment UUID from nextCursor; ordering is ascending creation time then UUID.", "schema": {"type": "string", "format": "uuid"}}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The comment thread, oldest first.", "content": {"application/json": {"schema": {"type": "object", "properties": {"signingId": {"type": "string", "format": "uuid"}, "hasMore": {"type": "boolean"}, "nextCursor": {"type": ["string", "null"], "format": "uuid"}, "comments": {"type": "array", "items": {"$ref": "#/components/schemas/Comment"}}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}}}, "post": {"tags": ["Signings"], "operationId": "addComment", "summary": "Add a note to a signing", "description": "Comments provide a private communication record for the integration\nand its audit trail. Access is limited to the integration; signer\ncommunications are handled through the signing ceremony.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"body": {"type": "string", "maxLength": 4000}, "authorLabel": {"type": "string", "maxLength": 120, "description": "Your own name for whoever wrote it. Echoed back."}}, "required": ["body"], "additionalProperties": false}}}}, "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The stored comment.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Comment"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}}}}, "/v1/erasure": {"post": {"tags": ["Signings"], "operationId": "eraseSignings", "summary": "Erase terminal signings in bulk", "description": "Purges the client's terminal signing records and any order-owned\nuploads. Pre-existing vault documents used through MCP are preserved.\nIn-flight signings are left untouched; erase one directly if\ncancellation is intended.\nProcesses at most `limit` resources across signings and headless signatures\n(default 20, maximum 100). After ten seconds of processing, finishes the\ncurrent resource and returns a continuation; a single storage operation\nstill depends on its transport timeout. Follow `nextCursor` while\n`hasMore` is true. The cursor binds the client and the initial cutoff;\n`before` may be omitted on continuation, or must match the first request.\nFailed resources are listed and skipped by the cursor so they cannot\nblock later pages. After finishing the traversal, retry failures with\na new request without a cursor. `hasMore: false` ends this traversal,\nnot a claim that failed resources or later-terminal records were erased.\n", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"before": {"type": "string", "format": "date-time"}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}, "cursor": {"type": "string", "maxLength": 2048}}, "additionalProperties": false}}}}, "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Number purged and number that must be retried.", "content": {"application/json": {"schema": {"type": "object", "properties": {"purged": {"type": "integer"}, "failed": {"type": "integer"}, "signaturesPurged": {"type": "integer", "description": "Present when headless signatures are enabled."}, "failedResources": {"type": "array", "items": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["signing", "signature"]}, "id": {"type": "string", "format": "uuid"}}, "required": ["kind", "id"]}}, "hasMore": {"type": "boolean"}, "nextCursor": {"type": ["string", "null"]}}, "required": ["purged", "failed", "failedResources", "hasMore", "nextCursor"]}}}}, "400": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signings/{signingId}/cancel": {"post": {"tags": ["Signings"], "operationId": "cancelSigning", "summary": "Cancel a signing", "description": "Retracts every invitation that has not been used: the ceremony link\ndies immediately, and the identity data the ceremony had captured\nabout those signers is erased.\n\nCollected signatures remain intact and the signed document remains\ndownloadable after cancellation.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "responses": {"400": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The signing is cancelled.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signing"}}}}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"description": "The signing had already ended, or every signer of a simple e-signature signed and the file is being sealed (`signing-finalizing`).", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}, "/v1/signings/{signingId}/document": {"get": {"tags": ["Signings"], "operationId": "downloadSignedDocument", "summary": "Download the signed document", "description": "The newest signed output. Available as soon as one signer has\nsigned, so a partially signed document can be fetched; the\n`X-Tvarka-Document-Sha256` header carries its digest. A simple\ne-signature (`level: esign`) has a result only once it is completed:\nthe sealed PDF, never a partial one. On a sandbox\nsimulation this streams the unsigned artifact instead, marked by an\n`X-Tvarka-Sandbox` header.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The signed document.", "headers": {"X-Tvarka-Document-Sha256": {"schema": {"type": "string"}, "description": "SHA-256 of the returned bytes."}, "X-Tvarka-Sandbox": {"schema": {"type": "string"}, "description": "Present only on a sandbox artifact\n(`simulated-artifact-no-signature`). The bytes carry no\nsignature.\n"}}, "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"description": "Nobody has signed yet.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}, "/v1/signings/{signingId}/evidence": {"get": {"tags": ["Signings"], "operationId": "downloadSigningEvidence", "summary": "Download the evidence of a simple e-signature", "description": "`level: esign` only (v1.11.0). A ZIP with the sealed PDF, the\nseparate signing summary when there is one, and every signing\nevent's timestamp token, bound to the signing's\n`evidence.referenceCode`. Reading it never signs, timestamps or\ncharges anything. A sandbox simulation returns a ZIP marked\n`X-Tvarka-Sandbox` that carries no signature.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "responses": {"200": {"description": "The evidence ZIP.", "headers": {"X-Tvarka-Evidence-Sha256": {"schema": {"type": "string"}, "description": "SHA-256 of the returned ZIP."}, "X-Tvarka-Reference-Code": {"schema": {"type": "string"}, "description": "The e-signature reference code the ZIP is bound to."}, "X-Tvarka-Sandbox": {"schema": {"type": "string"}, "description": "Present only on a sandbox simulation (`simulated-artifact-no-signature`)."}}, "content": {"application/zip": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"description": "`evidence-unavailable` until the signing is completed;\n`level-not-supported` on a qualified signing, whose evidence is\ninside the signed file.\n", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "410": {"description": "The evidence was erased.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signings/{signingId}/signers": {"post": {"tags": ["Signings"], "operationId": "addSigner", "summary": "Add a signer to a live signing", "description": "On a `sequential` signing the newcomer joins the END of the queue:\nthey come back `waiting`, their link stays dead until their turn,\nand no delivery goes out before it. Only a parallel signing hands\nback a live ceremony URL immediately.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SignerRequest"}}}}, "responses": {"403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The signer and their ceremony.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signer"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signings/{signingId}/signers/{signerId}": {"patch": {"tags": ["Signings"], "operationId": "updateSignerMethods", "summary": "Update a pending signer's allowed methods", "parameters": [{"$ref": "#/components/parameters/SigningId"}, {"$ref": "#/components/parameters/SignerId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"methods": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/components/schemas/SigningMethod"}}}, "required": ["methods"], "additionalProperties": false}}}}, "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The updated signer.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signer"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}}}, "delete": {"tags": ["Signings"], "operationId": "removeSigner", "summary": "Remove a pending signer", "description": "Retracts the ceremony link before removing the signer.", "parameters": [{"$ref": "#/components/parameters/SigningId"}, {"$ref": "#/components/parameters/SignerId"}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "204": {"description": "The signer was removed."}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signings/{signingId}/signers/{signerId}/remind": {"post": {"tags": ["Signings"], "operationId": "remindSigner", "summary": "Remind one signer", "description": "Re-sends the invitation email. One reminder per signer per hour.", "parameters": [{"$ref": "#/components/parameters/SigningId"}, {"$ref": "#/components/parameters/SignerId"}], "responses": {"502": {"$ref": "#/components/responses/Problem"}, "400": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The reminder was sent.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signer"}}}}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "429": {"description": "A reminder was sent to this signer less than an hour ago. Retry-After gives the remaining cooldown in seconds.", "headers": {"Retry-After": {"schema": {"type": "integer", "minimum": 1, "maximum": 3600}}}, "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}, "/v1/signings/{signingId}/simulate": {"post": {"tags": ["Signings"], "operationId": "simulateSigning", "summary": "Drive a sandbox signing to an outcome", "description": "Sandbox keys only. Moves a signing to `completed`, `declined` or\n`expired` so an integrator can exercise each terminal path without\nwaiting. `complete` simulates the lifecycle: signer status is\n`simulated`, completion mode is `sandbox_simulation`, and no\nsignature is created. It does return a downloadable artifact so the\nsuccess path is testable, flagged `sandbox: true`. The sandbox adds\nno signature: an unsigned PDF comes back stamped and unsigned,\nanything already signed comes back byte-identical.\n", "parameters": [{"$ref": "#/components/parameters/SigningId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"action": {"type": "string", "enum": ["complete", "decline", "expire"]}, "signerEmail": {"type": "string", "format": "email", "description": "Which signer declines. Defaults to the first."}, "reason": {"type": "string"}}, "required": ["action"], "additionalProperties": false}}}}, "responses": {"402": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The signing after the simulated outcome.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signing"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "403": {"description": "The key is a production key.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "404": {"$ref": "#/components/responses/Problem"}, "422": {"description": "The requested sandbox stamp could not be prepared.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "409": {"description": "The signing is already terminal, so there is no outcome left to\nsimulate.\n", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}, "/v1/me": {"get": {"tags": ["Account"], "operationId": "getMe", "summary": "Who the key acts for", "description": "The workspace and environment this key or connection acts for, and\nthe email of the person it acts as. Automation platforms call it to\ntest a new connection and to name it (v1.12.0).\n", "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The workspace behind the key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Me"}}}}}}}, "/v1/webhooks": {"get": {"tags": ["Webhooks"], "operationId": "listWebhooks", "summary": "List webhook subscriptions", "description": "The active webhook subscriptions of this integration (v1.12.0).", "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Active subscriptions, oldest first.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSubscriptionList"}}}}}}, "post": {"tags": ["Webhooks"], "operationId": "createWebhook", "summary": "Subscribe a URL to signing events", "description": "Delivers the chosen events of every signing this integration\ncreates to `url` (the `subscriptionEvent` webhook below). This is\nwhat Zapier, Make and Power Automate call when a user turns a\ntrigger on. The same URL again replaces its event list and returns\nthe same subscription, so a retried subscribe never doubles\ndeliveries. `url` is checked like `webhookUrl`: public HTTPS, at\nmost 500 characters, redirects never followed. An integration holds\nat most 50 subscriptions (v1.12.0).\n", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateWebhookSubscription"}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "201": {"description": "Subscribed.", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}, "description": "The subscription's URL; DELETE it to unsubscribe."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSubscription"}}}}, "409": {"description": "The integration already holds 50 subscriptions.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}, "/v1/webhooks/deliveries": {"get": {"tags": ["Webhooks"], "operationId": "listWebhookDeliveries", "summary": "List recent webhook deliveries", "description": "Returns recent webhook delivery attempts for this API client across\nsigning, headless signature, subscription, form and timestamp channels\n(v1.29.0). Payloads never contain document bytes or personal data.\n", "parameters": [{"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending", "delivered", "exhausted", "discarded"]}}, {"name": "event", "in": "query", "schema": {"type": "string", "maxLength": 80}}, {"name": "signingId", "in": "query", "schema": {"type": "string", "format": "uuid"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}], "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Recent webhook delivery attempts, newest first.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookDeliveryList"}}}}}}}, "/v1/webhooks/deliveries/{deliveryId}/retry": {"post": {"tags": ["Webhooks"], "operationId": "retryWebhookDelivery", "summary": "Retry a webhook delivery", "description": "Re-queues a non-delivered webhook event owned by this API client for\nimmediate delivery and extends its retry window (v1.29.0). Already\ndelivered events, events of a removed subscription (unsubscribed or\nanswered `410 Gone`) and a blocked client answer 409. A delivery a\nworker is sending right now also answers 409; its result is recorded\nwithin two minutes.\n", "parameters": [{"$ref": "#/components/parameters/DeliveryId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "202": {"description": "Delivery re-queued.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookDelivery"}}}}}}}, "/v1/webhooks/{webhookId}": {"get": {"tags": ["Webhooks"], "operationId": "getWebhook", "summary": "Get a webhook subscription", "parameters": [{"$ref": "#/components/parameters/WebhookId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The subscription.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSubscription"}}}}}}, "delete": {"tags": ["Webhooks"], "operationId": "deleteWebhook", "summary": "Unsubscribe", "description": "Stops deliveries to this subscription and drops its undelivered\nevents. Deleting a subscription that is already removed succeeds\ntoo, so a platform may retry it safely (v1.12.0).\n", "parameters": [{"$ref": "#/components/parameters/WebhookId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "204": {"description": "Unsubscribed."}}}}, "/v1/signatures": {"post": {"tags": ["Signatures"], "operationId": "createSignature", "summary": "Start a headless signature", "description": "Opens the first confirmation on the signer's phone at once and\nanswers `202` with its verification code. Show the code; poll\n`GET /v1/signatures/{signatureId}` or wait for the webhook.\n\nRefusals at create time are never billed: `402 payment-required`\nwith `recoveryUrl` when the\nworkspace cannot pay for one signature, `409 signer-busy` when the\nsigner already has an active request elsewhere (not queued; retry\nonce it ends), `400 validation-failed` listing every rejected\nfield with a JSON Pointer, `422 interaction-unavailable` when a\nQR code or app link is asked for and not switched on, and `422\nsigner-unreachable` when the provider refused because of the person\nor the request, for example when no account exists for this method.\nThe same request would be refused again. A `503` that\ncarries `Retry-After` means provably nothing started: retry with the\nsame Idempotency-Key. A start that may have reached the phone\nanswers `202` with `status: failed` and `failureReason:\ninitiation_unknown`, never a second start.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateSignatureRequest"}}}}, "responses": {"202": {"description": "The first confirmation is on the signer's phone.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signature"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "409": {"description": "The signer already has an active request, or the Idempotency-Key was reused with other input.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "413": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signatures/{signatureId}": {"get": {"tags": ["Signatures"], "operationId": "getSignature", "summary": "State, current step and code, result", "parameters": [{"$ref": "#/components/parameters/SignatureId"}], "responses": {"200": {"description": "The signature.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signature"}}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signatures/{signatureId}/cancel": {"post": {"tags": ["Signatures"], "operationId": "cancelSignature", "summary": "Cancel a pending signature", "description": "A confirmation already on the phone cannot be withdrawn there; if\nthe signer still confirms it, the result is discarded and not\nbilled.\n", "parameters": [{"$ref": "#/components/parameters/SignatureId"}], "responses": {"200": {"description": "The signature is cancelled.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signature"}}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"description": "The signature had already ended.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signatures/{signatureId}/document": {"get": {"tags": ["Signatures"], "operationId": "downloadSignature", "summary": "Download the signed artifact", "description": "`.p7s` (`application/pkcs7-signature`) for `cades-detached`, the\nsigned PDF for `pades`, the `.pdf.p7m` (`application/pkcs7-mime`)\nfor `cades-enveloping`, the signed XML for `xades-enveloped`, the\n`.xml.p7m` for `cades-enveloping-xml`, the container for `asice` and\n`edoc` (`application/vnd.etsi.asic-e+zip`) and the JWS for `jades`\n(`application/jose+json`). Kept for 30 days or until\n`/v1/erasure`; afterwards `410`. A sandbox simulation streams an\nartifact with no signature, marked by `X-Tvarka-Sandbox`.\n", "parameters": [{"$ref": "#/components/parameters/SignatureId"}], "responses": {"200": {"description": "The signed artifact.", "headers": {"X-Tvarka-Document-Sha256": {"schema": {"type": "string"}, "description": "SHA-256 of the returned bytes."}, "X-Tvarka-Sandbox": {"schema": {"type": "string"}, "description": "Present only on a sandbox artifact (`simulated-artifact-no-signature`)."}}, "content": {"application/pkcs7-signature": {"schema": {"type": "string", "format": "binary"}}, "application/pdf": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"description": "The signature is not signed.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "410": {"description": "The artifact was erased; the signature record remains.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/signatures/{signatureId}/simulate": {"post": {"tags": ["Signatures"], "operationId": "simulateSignature", "summary": "Drive a sandbox signature to an outcome", "description": "Sandbox keys only. `sign` returns your XML unchanged, or an empty\n`.p7s` placeholder for a hash, flagged `sandbox: true` and\n`completionMode: sandbox_simulation`: no signature is added.\n`fail` takes an optional `reason` from `SignatureFailureReason`.\n", "parameters": [{"$ref": "#/components/parameters/SignatureId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"action": {"type": "string", "enum": ["sign", "decline", "expire", "fail"]}, "reason": {"$ref": "#/components/schemas/SignatureFailureReason"}}, "required": ["action"], "additionalProperties": false}}}}, "responses": {"200": {"description": "The signature after the simulated outcome.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signature"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"description": "The key is a production key.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"description": "The signature had already ended.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}}, "webhooks": {"signingEvent": {"post": {"summary": "Signing event", "description": "Sent to `webhookUrl` as a signing progresses. Deliveries carry\n`X-Tvarka-Signature: sha256=<HMAC-SHA256 of the raw body>` keyed with\nyour webhook secret - verify it before acting - plus\n`X-Tvarka-Idempotency-Key` and `X-Tvarka-Event`.\n\nPrefer `X-Tvarka-Signature-V2: t=<unix seconds>,v1=<hex>`, where\n`v1` is the HMAC-SHA256 of `t + \".\" + raw body` under the same secret\nand `t` equals `X-Tvarka-Timestamp`. Reject deliveries whose `t` is\nmore than 5 minutes from your clock: a replayed delivery fails.\n\nRetried with backoff on 5xx and transport failures. Delivery is a\nconvenience, never the only way to learn an outcome: polling always\nworks, and a failed delivery never changes a signing's state.\n\nThe payload never carries a signer's identity data - no personal\ncode, no certificate subject, no phone number. It echoes the email\nyou supplied and nothing more.\n", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"event": {"type": "string", "enum": ["signing.signer_signed", "signing.signer_declined", "signing.signer_failed", "signing.completed", "signing.declined", "signing.cancelled", "signing.expired", "signing.failed"]}, "signingId": {"type": "string", "format": "uuid"}, "status": {"$ref": "#/components/schemas/SigningStatus"}, "externalId": {"type": "string"}, "occurredAt": {"type": "string", "format": "date-time"}, "completionMode": {"type": "string", "enum": ["qes_ceremony", "esign_ceremony", "sandbox_simulation"]}, "level": {"type": "string", "enum": ["esign"], "description": "Present on a simple e-signature."}, "signer": {"type": "object", "properties": {"signerId": {"type": "string", "format": "uuid"}, "email": {"type": "string", "format": "email"}, "status": {"$ref": "#/components/schemas/SignerStatus"}, "declineReason": {"type": "string"}}}, "document": {"$ref": "#/components/schemas/SignedDocument"}}}}}}, "responses": {"401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Acknowledged. Any 2xx stops redelivery."}}}}, "subscriptionEvent": {"post": {"summary": "Webhook subscription event", "description": "Sent to each subscription registered with `POST /v1/webhooks` for\nthe events it chose (v1.12.0). Same headers, HMAC signatures and\n72-hour retry as `signingEvent`, under the same webhook secret.\n`eventId` equals the `X-Tvarka-Idempotency-Key` header: use it to\nprocess each event once. `signing` is the signing at the moment of\nthe event, as `GET /v1/signings/{signingId}` shows it, without\nceremony links. Answer `410 Gone` to remove the subscription.\n", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"event": {"$ref": "#/components/schemas/WebhookEventName"}, "eventId": {"type": "string"}, "webhookId": {"type": "string", "format": "uuid"}, "signingId": {"type": "string", "format": "uuid"}, "status": {"$ref": "#/components/schemas/SigningStatus"}, "externalId": {"type": "string"}, "occurredAt": {"type": "string", "format": "date-time"}, "completionMode": {"type": "string", "enum": ["qes_ceremony", "esign_ceremony", "sandbox_simulation"]}, "level": {"type": "string", "enum": ["esign"]}, "signer": {"type": "object", "properties": {"signerId": {"type": "string", "format": "uuid"}, "email": {"type": "string", "format": "email"}, "status": {"$ref": "#/components/schemas/SignerStatus"}, "declineReason": {"type": "string"}}}, "document": {"$ref": "#/components/schemas/SignedDocument"}, "signing": {"$ref": "#/components/schemas/Signing"}}, "required": ["event", "eventId", "webhookId", "signingId", "status", "occurredAt", "signing"]}}}}, "responses": {"401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Acknowledged. Any 2xx stops redelivery."}, "410": {"description": "Gone. Tvarka removes the subscription."}}}}, "signatureEvent": {"post": {"summary": "Headless signature event", "description": "Same delivery, headers, HMAC signatures and 72-hour retry as\n`signingEvent`. `signature.confirmation_required` carries the new\n`verificationCode` when the second confirmation starts. Never\npersonal data: no personal code, no phone, no certificate subject.\n", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"event": {"type": "string", "enum": ["signature.confirmation_required", "signature.signed", "signature.declined", "signature.expired", "signature.failed", "signature.cancelled"]}, "signatureId": {"type": "string", "format": "uuid"}, "status": {"$ref": "#/components/schemas/SignatureStatus"}, "occurredAt": {"type": "string", "format": "date-time"}, "externalId": {"type": "string"}, "step": {"type": "string", "enum": ["authentication", "signing"]}, "verificationCode": {"type": "string"}, "nextAction": {"$ref": "#/components/schemas/NextAction"}, "failureReason": {"$ref": "#/components/schemas/SignatureFailureReason"}, "completionMode": {"type": "string", "enum": ["signed", "sandbox_simulation"]}, "sandbox": {"type": "boolean"}, "document": {"type": "object", "properties": {"sha256": {"type": "string"}}}}, "required": ["event", "signatureId", "status", "occurredAt"]}}}}, "responses": {"401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Acknowledged. Any 2xx stops redelivery."}}}}, "formRequestEvent": {"post": {"summary": "Form request event", "description": "Sent to a form request's `webhookUrl` and to every webhook\nsubscription of the workspace that asked for the event, signed and\nretried like `signingEvent` (v1.16.0). `form_request.completed`\ncarries the values under their semantic identifiers and the links to\nthe signed PDF and the evidence. Other events carry the state only.\nDeduplicate by `eventId`.\n", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/FormRequestEvent"}}}}, "responses": {"200": {"description": "Acknowledge within 10 seconds."}}}}}, "components": {"securitySchemes": {"agentOAuth": {"type": "oauth2", "description": "Agent connections for Claude, ChatGPT, Gemini, Copilot and any MCP\nclient. OAuth 2.1 authorization code with PKCE S256, dynamic client\nregistration (RFC 7591) and RFC 9207 `iss` in every authorization\nresponse. Discovery: `/.well-known/oauth-protected-resource/mcp`\n(RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414).\nThe person signs in with their eID, picks the company and allows the\nconnection; the token then acts exactly as that person's own API key\nwould, with the same role re-check on every request. Registration\naccepts the callback URLs of supported agent platforms and loopback\naddresses. Access tokens live one hour; refresh tokens rotate and a\nreused refresh token revokes the connection. The person sees and\nrevokes connections under Settings, API settings, Connected apps.\nHeadless signatures (`/v1/signatures`) are not available to agent\nconnections.\n", "flows": {"authorizationCode": {"authorizationUrl": "https://sign-api.tvarka.pro/oauth/authorize", "tokenUrl": "https://sign-api.tvarka.pro/oauth/token", "refreshUrl": "https://sign-api.tvarka.pro/oauth/token", "scopes": {"sign.read": "Read signings and download signed documents.", "sign.signings": "Send documents for signature, add and remind signers, cancel signings."}}}}, "bearerAuth": {"type": "http", "scheme": "bearer", "description": "`Authorization: Bearer <key>` for REST and MCP. Every active, identified\ncompany member with Sign access has production API access automatically.\nSelect the company, open https://sign.tvarka.pro/sign/app/settings/#api-keys\nand click Show or Copy. The secret is prepared on first use and reused.\nA `tsk_live_` key acts on production; existing `tsk_test_` sandbox keys\nremain supported. Sandbox is retired from ordinary onboarding.\n\nCompany administrators invite users by email and select Employee or\nRepresentative (all rights). The optional email checkbox only requests\nan AES-256 ZIP after identity confirmation; it does not grant API access.\nThe ZIP includes the API key and webhook secret. Its password is the\nlast four personal-code digits, including leading zeroes. Email failure\ndoes not roll back joining the company. Only the owner can reveal keys.\nHistorical hash-only keys remain valid; first Show/Copy prepares a\nrecoverable companion on the same integration. Deliberate revocations\nare never silently undone. Existing integration IDs and history remain.\n\nUsers and access has visible Change rights, Send API key and API settings\nactions without a More menu. A managing employee who may manage payments\ncan administer billing, and one who may manage people can invite others. Pending and failed email\ndelivery appear inline; transport acceptance is not proof of inbox delivery.\n\nManager Replace key gives older keys at most 24 hours of overlap;\nthe successor appears in employee Settings. Manage access offers\nindividual-key revocation, whole-integration revocation, immediate\nreplacement, planned rotation and webhook-secret changes. Advanced\nreplacement, planned rotation and webhook-secret changes require\nrecent eID confirmation. Rotation/revocation leaves the webhook secret\nunchanged unless it is explicitly changed separately.\n\nThe key acts as a named workspace user. Removing that person's role\npermanently revokes its API access; restoring the role does not revive\nkeys. Suspended access blocks API use. Revocation stops the affected\nkeys immediately but does not cancel already-created signing orders.\nATK and Due Diligence credentials are separate. Full guidance:\nhttps://sign-api.tvarka.pro/docs#keys.\n"}, "apiKeyHeader": {"type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "The same API key as `bearerAuth`, in its own header, for platforms\nwhose API key connections send a key exactly as typed (v1.12.0).\nSend one of the two, not both.\n"}}, "parameters": {"IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional tenant-and-operation-scoped create key (1-128 visible ASCII characters). Identical input replays the original response; changed input or an unresolved execution returns 409. After 90 days the response expires but the key remains reserved. Do not change keys to retry a request with an uncertain outcome.", "schema": {"type": "string", "minLength": 1, "maxLength": 128}}, "BatchId": {"name": "batchId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "FileToken": {"name": "fileToken", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "SigningId": {"name": "signingId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "SignerId": {"name": "signerId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "SignatureId": {"name": "signatureId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "WebhookId": {"name": "webhookId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "DeliveryId": {"name": "deliveryId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "TemplateId": {"name": "templateId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "BulkSendId": {"name": "bulkSendId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "FormRequestId": {"name": "formRequestId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "KioskSessionId": {"name": "kioskSessionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}}, "responses": {"Problem": {"description": "An RFC 9457 problem document.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}, "schemas": {"Kiosk": {"type": "object", "properties": {"kioskId": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "place": {"type": ["string", "null"]}, "paired": {"type": "boolean"}, "online": {"type": "boolean", "description": "A heartbeat in the last 90 seconds."}, "busy": {"type": "boolean", "description": "A kiosk session is open on it."}}}, "CreateKioskSessionRequest": {"type": "object", "required": ["kioskId"], "description": "A PDF to sign (`product: sign`, the default) needs `title` and `document`. A form request (`product: forms`) needs `formRequestId`.", "properties": {"kioskId": {"type": "string", "format": "uuid"}, "product": {"type": "string", "enum": ["sign", "forms"], "default": "sign"}, "formRequestId": {"type": "string", "format": "uuid", "description": "With product forms, the form request to fill and sign on the kiosk."}, "assisted": {"type": "boolean", "default": false, "description": "Start in assisted mode."}, "title": {"type": "string", "maxLength": 255}, "document": {"type": "object", "description": "One PDF, through the same intake as a signing's `document`.", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}, "fileToken": {"type": "string", "format": "uuid"}, "markdown": {"type": "string"}, "url": {"type": "string", "format": "uri"}}, "additionalProperties": false}, "signer": {"type": "object", "properties": {"name": {"type": "string", "description": "Left empty, the person types the name on the tablet."}, "email": {"type": "string", "format": "email", "description": "Receives the signed PDF."}, "phone": {"type": "string", "description": "Required with identity sms."}}, "additionalProperties": false}, "identity": {"type": "string", "enum": ["attended", "sms"], "default": "attended"}}, "additionalProperties": false}, "KioskSession": {"type": "object", "properties": {"kioskSessionId": {"type": "string", "format": "uuid"}, "kioskId": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["waiting", "in_progress", "assisted", "ready", "signing", "completed", "cancelled", "expired", "failed"]}, "assisted": {"type": "boolean"}, "title": {"type": "string"}, "signerName": {"type": ["string", "null"]}, "identity": {"type": "string", "enum": ["attended", "sms"]}, "createdAt": {"type": "string", "format": "date-time"}, "completedAt": {"type": ["string", "null"], "format": "date-time"}, "revision": {"type": "integer"}, "product": {"type": "string", "enum": ["sign", "forms", "sauga"]}, "formRequestId": {"type": ["string", "null"], "format": "uuid", "description": "With product forms."}, "referenceCode": {"type": "string", "description": "The public check code, once completed."}}}, "CreateSignatureRequest": {"type": "object", "additionalProperties": false, "required": ["method", "document", "renderHash"], "properties": {"method": {"type": "string", "enum": ["smart_id", "mobile_id"]}, "interaction": {"type": "object", "additionalProperties": false, "required": ["type"], "description": "How the signer is reached (v1.11.0). `notification` (default):\na prompt on their phone and a verification code you show. `qr`\nand `app_link`: Smart-ID only; the signer picks the account by\nQR code or app link and no personal code is needed.\n", "properties": {"type": {"type": "string", "enum": ["notification", "qr", "app_link"], "default": "notification"}}}, "returnUrl": {"type": "string", "format": "uri", "maxLength": 500, "description": "`app_link` only, and required there: an exact HTTPS URL\nregistered for this API client. Requires `returnState`.\n"}, "returnState": {"type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$", "description": "Random per-browser-session value, returned as `state`."}, "visibleSignature": {"oneOf": [{"type": "boolean"}, {"$ref": "#/components/schemas/VisibleSignature"}], "description": "`pades` only (v1.13.0): the visible stamp is your choice.\nOmitted or `false`: no stamp. `true`: the stamp in the default\ncorner. An object: exactly one of coordinates or an existing\nempty signature field, with the same checks as a hosted signer's\n`visibleSignature`.\n"}, "signer": {"type": "object", "additionalProperties": false, "description": "Required for `notification`. Optional for `qr` and `app_link`,\nwhere `personalCode` alone accepts only that person.\n", "properties": {"personalCode": {"type": "string", "pattern": "^(PNO(EE|LT)-)?[0-9]{11}$", "description": "Identity lock: only this person's signature is accepted. Never\nreturned and never sent in webhooks. Required for\n`notification`. The country is read as for a hosted signer's\n`personalCode`: bare digits follow your company's country, and\n`PNOEE-` or `PNOLT-` names it (v1.27.2). An Estonian code locks\na `qr` or `app_link` signature; `notification` takes a\nLithuanian code.\n"}, "phoneNumber": {"type": "string", "pattern": "^\\+3706[0-9]{7}$", "description": "Required for `mobile_id`, refused otherwise."}}}, "document": {"type": "object", "additionalProperties": false, "required": ["name", "profile"], "description": "Exactly one of `hash`, `pdf` or `file`. For `asice` and `edoc`\nthe file takes `name` inside the container.\n", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 120}, "profile": {"type": "string", "enum": ["cades-detached", "pades", "cades-enveloping", "xades-enveloped", "cades-enveloping-xml", "asice", "edoc", "jades"]}, "hash": {"type": "object", "additionalProperties": false, "required": ["algorithm", "value"], "description": "The digest to sign, for `cades-detached`.", "properties": {"algorithm": {"type": "string", "enum": ["sha256"]}, "value": {"type": "string", "format": "byte", "description": "Base64, exactly 32 bytes."}}}, "pdf": {"type": "object", "additionalProperties": false, "required": ["content"], "description": "The PDF to sign, for `pades` and `cades-enveloping`. Base64, at most 15 MiB decoded;\nmust be an unencrypted PDF.\n", "properties": {"content": {"type": "string", "format": "byte"}}}, "file": {"type": "object", "additionalProperties": false, "required": ["content"], "description": "The file to sign (v1.21.0). Base64, at most 15 MiB decoded, not\nempty. A well-formed XML for `xades-enveloped` and\n`cades-enveloping-xml` (no DTD or entities; not yet signed for\n`xades-enveloped`), UTF-8 JSON for `jades`, any file for\n`asice` and `edoc`.\n", "properties": {"content": {"type": "string", "format": "byte"}}}}}, "display": {"type": "object", "additionalProperties": false, "properties": {"text": {"type": "string", "description": "Shown in the signer's app. Smart-ID shows up to 60 characters;\nMobile-ID up to 40, or 20 when the text has a Lithuanian\nletter with a diacritic. Printable characters only. Default:\n`<company name>: pasirašymas`.\n"}}}, "renderHash": {"type": "object", "additionalProperties": false, "required": ["algorithm", "value"], "description": "Digest of what you showed the signer. Kept as evidence.", "properties": {"algorithm": {"type": "string", "enum": ["sha256", "sha384", "sha512"]}, "value": {"type": "string", "format": "byte"}}}, "externalId": {"type": "string", "maxLength": 120}, "webhookUrl": {"type": "string", "format": "uri", "description": "Public HTTPS URL."}}}, "Signature": {"type": "object", "required": ["id", "status", "method", "step", "createdAt"], "properties": {"id": {"type": "string", "format": "uuid"}, "status": {"$ref": "#/components/schemas/SignatureStatus"}, "method": {"type": "string", "enum": ["smart_id", "mobile_id"]}, "interaction": {"type": "string", "enum": ["notification", "qr", "app_link"]}, "nextAction": {"$ref": "#/components/schemas/NextAction"}, "step": {"type": "string", "enum": ["authentication", "signing"], "description": "The confirmation in flight. Tvarka decides which run."}, "verificationCode": {"type": ["string", "null"], "description": "Show this to the signer while `pending`."}, "expiresAt": {"type": "string", "format": "date-time"}, "externalId": {"type": ["string", "null"]}, "document": {"type": "object", "properties": {"name": {"type": "string"}, "profile": {"type": "string"}, "inputSha256": {"type": ["string", "null"], "description": "Hex digest the signature covers."}}}, "visibleSignature": {"description": "The stamp chosen at create (v1.13.0): `false` for none, `true` for\nthe default corner, the accepted placement, or null for a hash.\n", "oneOf": [{"type": "boolean"}, {"$ref": "#/components/schemas/VisibleSignature"}, {"type": "null"}]}, "failureReason": {"$ref": "#/components/schemas/SignatureFailureReason"}, "sandbox": {"type": "boolean"}, "completionMode": {"type": "string", "enum": ["signed", "sandbox_simulation"]}, "createdAt": {"type": "string", "format": "date-time"}, "completedAt": {"type": ["string", "null"], "format": "date-time"}, "result": {"type": "object", "description": "Present once `signed`.", "properties": {"profile": {"type": "string"}, "level": {"type": ["string", "null"], "description": "For example CAdES-BASELINE-LT."}, "sha256": {"type": "string"}, "bytes": {"type": "integer"}, "signingTime": {"type": ["string", "null"], "format": "date-time"}, "timestampTime": {"type": ["string", "null"], "format": "date-time"}, "certificate": {"type": ["object", "null"], "properties": {"subjectCommonName": {"type": "string"}, "issuer": {"type": "string"}, "serialNumber": {"type": "string", "description": "Certificate serial, hex."}, "notAfter": {"type": "string", "format": "date-time"}, "qualified": {"type": "boolean", "description": "The certificate states it is qualified and on a qualified\nsignature creation device. A statement in the certificate,\nnot a trusted-list verdict.\n"}}}, "validation": {"type": ["object", "null"], "description": "Advisory. `notApplicable` for `cades-detached`: a detached\nsignature over a hash is validated beside the document, which\nTvarka never receives.\n"}, "available": {"type": "boolean", "description": "False once the artifact was erased."}}}}}, "NextAction": {"type": "object", "required": ["type", "revision"], "description": "What to show the signer now (v1.11.0). `revision` grows with every\nstep and once more at the end; ignore a webhook whose revision is\nolder than the one you hold, and poll when unsure.\n", "properties": {"type": {"type": "string", "enum": ["compare_code", "confirm_certificate", "scan_qr", "open_app", "wait", "none"]}, "revision": {"type": "integer", "minimum": 1}, "verificationCode": {"type": "string", "description": "With `compare_code`."}, "qrLink": {"type": "string", "format": "uri", "description": "With `scan_qr`. Show as a QR code; it changes every second."}, "refreshAfterSeconds": {"type": "integer", "description": "With `scan_qr`: fetch a new link after this long."}, "appLink": {"type": "string", "format": "uri", "description": "With `open_app`: open on the signer's phone."}, "expiresAt": {"type": "string", "format": "date-time"}}}, "SignatureStatus": {"type": "string", "enum": ["pending", "signed", "declined", "expired", "failed", "cancelled"]}, "SignatureFailureReason": {"type": "string", "enum": ["identity_mismatch", "certificate_not_qualified", "certificate_rotated", "provider_error", "timestamp_unavailable", "initiation_unknown"], "description": "`identity_mismatch` - the certificate belongs to another person.\n`certificate_not_qualified` - the certificate cannot sign documents.\n`certificate_rotated` - the signer's certificate changed since Tvarka\nlast saw it; the new one is kept, so a retry needs one confirmation.\n`provider_error` - the signing service failed.\n`timestamp_unavailable` - no qualified timestamp could be obtained.\n`initiation_unknown` - the start may have reached the signer's phone\nbut no answer came back; it is never repeated. Ask the signer to\ndismiss any prompt and retry after two minutes.\nNone of these is billed.\n"}, "CreateSigningRequest": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 255, "description": "Shown to signers on the ceremony page and in their email."}, "document": {"type": "object", "properties": {"name": {"type": "string", "description": "Filename with extension. The extension selects the family:\n`.pdf`; `.docx`, `.doc`, `.odt`, `.rtf`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.odp`, `.txt`, `.jpg`, `.jpeg` and `.png`, converted to PDF/A-2b and signed as a\nPDF (v1.9.0); `.asice`/`.sce`/`.bdoc`/`.edoc` for ASiC-E,\n`.asics`/`.scs` for ASiC-S, and `.adoc`/`.bedoc`/`.cedoc`/\n`.gedoc`/`.ggedoc` for the ADOC family. An enveloping `.p7m`\ncan take a parallel signature. A detached signature has no document to sign.\nFor containers the extension only decides that we look\ninside - the container's own mimetype member decides what\nit is. `.mdoc` is refused: an MDOC takes a first signature\nonly.\n"}, "content": {"type": "string", "format": "byte", "description": "Base64-encoded bytes, up to 15 MiB decoded. Provide exactly\none of `content`, `fileToken`, `markdown` or `url`.\n"}, "fileToken": {"type": "string", "format": "uuid", "description": "A reusable upload from `POST /v1/files`, referenced instead\nof carrying the bytes again. The bytes are copied into the\nsigning at creation, so purging the file later never\nreaches into a signing that already used it. Provide\nexactly one of `content`, `fileToken`, `markdown` or `url`.\n"}, "markdown": {"type": "string", "minLength": 10, "maxLength": 200000, "description": "The document as Markdown (CommonMark with tables and\nstrikethrough). Tvarka renders it to an A4 PDF/A-2b and signs\nthat PDF. Raw HTML is shown as text and nothing remote is\nloaded, so the PDF is exactly the text. The first `# `\nheading becomes the title when `title` is omitted, and\n`name` defaults to that title.\n"}, "url": {"type": "string", "format": "uri", "description": "A public HTTPS link Tvarka downloads the document from:\na PDF, a convertible Office file or image (converted to\nPDF/A-2b, v1.9.0), an appendable ASiC-E or a signed\nADOC-family container. Private and loopback addresses are refused, each\nredirect (up to three) is re-checked, and the download is\nbounded by the document size limit and 20 seconds. `name`\ndefaults to the last path segment.\n"}, "flatten": {"type": "boolean", "default": false, "description": "PDF only. Draw every form field's appearance into page\ncontent and drop the AcroForm, so what a reader sees cannot\ndepend on a viewer's form handling. Fails closed: if any\nwidget has no appearance stream Tvarka can draw faithfully,\nnothing is flattened and the response names those fields.\nSigning a live AcroForm without this is perfectly valid -\nthe signature still detects any later edit.\nLimits per request (shared across batch documents): 1,000\npages, 5,000 widgets, 10,000 annotations, 10,000 field-tree\nnodes and field depth 64. Complexity is checked before\ncloning. A cooperative 20-second budget checks between PDF\noperations; it does not interrupt a parser or writer call.\nRefusal returns 400 with the flatten error pointer. Split\nthe batch or flatten before upload.\n"}}, "additionalProperties": false}, "container": {"type": "object", "description": "Compose a NEW container from several files and sign that, instead\nof posting one finished document. Mutually exclusive with\n`document`; exactly one of the two is required.\n", "properties": {"format": {"type": "string", "enum": ["asice", "adoc"], "description": "`asice` takes PDFs only. `adoc` is the Lithuanian ADOC-V1.0\npackage and takes `.pdf` and `.xlsx`. The first file is the\nmain document; the rest are appendices.\n"}, "files": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "object", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}}, "required": ["name", "content"], "additionalProperties": false}}}, "required": ["format", "files"], "additionalProperties": false}, "level": {"type": "string", "enum": ["qualified", "esign"], "default": "qualified", "description": "Fixed at creation (v1.11.0). `qualified`: each signer signs with\ntheir eID. `esign`: a simple e-signature on the Tvarka page, one\nPDF, signers with `email`, `name`, `language` and\n`authentication` only.\n"}, "templateId": {"type": "string", "format": "uuid", "description": "Send a saved template (v1.14.0). The document, `level`,\n`signingOrder` and each role's placement come from the template,\nso `document`, `container`, `signers`, `level` and `signingOrder`\nare refused beside it. `title` defaults to the template's title\nand `expiresInDays` to its expiry.\n"}, "templateRoles": {"type": "array", "maxItems": 20, "description": "With `templateId`: who signs each role. A role with a saved\nsigner may be left out; every other role needs an entry with an\nemail. A fault in the template's saved data points at `/templateId`.\n", "items": {"$ref": "#/components/schemas/TemplateRolePrefill"}}, "signers": {"type": "array", "minItems": 1, "maxItems": 20, "description": "Participants in input order, which is the release order for a\nsequential signing. Each email may appear once.\n", "items": {"$ref": "#/components/schemas/SignerRequest"}}, "delivery": {"type": "string", "enum": ["link", "email"], "default": "link", "description": "`link` returns a `ceremonyUrl` per signer for you to deliver.\n`email` has Tvarka email each signer in your entity's name.\n"}, "returnUrl": {"type": "string", "format": "uri", "maxLength": 500, "description": "Exact HTTPS URL registered for this API client. Requires returnState. After signing, decline or expiry the same browser tab returns here. Browser results are navigation hints, never proof of signing; confirm through GET signing or a verified webhook."}, "returnState": {"type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$", "description": "Random per-browser-session correlation value; required with returnUrl. Compare it on return. Never put personal data or secrets here."}, "embedOrigin": {"type": "string", "format": "uri", "maxLength": 255, "description": "Exact HTTPS parent origin (`https://host[:port]`, no path, query or\nwildcard) registered for this API client in Tvarka Sign API settings\n(v1.29.0). Allows framing this signing's ceremony solely on that\norigin via per-response `Content-Security-Policy: frame-ancestors`\nand emits origin-locked `window.parent.postMessage` lifecycle events\n(`type: \"tvarka:signing\"`). Removing the origin from settings blocks\nframing immediately. A host with non-ASCII letters is stored in\nits ASCII (punycode) form. A signer with `authentication` of type\n`access_code` or `sms` cannot be embedded, because the browser\nkeeps the passed step in a cookie it does not send inside a\ncross-site iframe; such a request is refused with `400` at that\nsigner's `authentication` pointer.\n"}, "webhookUrl": {"type": "string", "format": "uri", "description": "Public HTTPS URL for signing events. Optional."}, "externalId": {"type": "string", "maxLength": 120, "description": "Your own reference, echoed on every response and webhook."}, "signingOrder": {"type": "string", "enum": ["parallel", "sequential"], "default": "parallel"}, "softDeadlineInDays": {"type": "integer", "minimum": 1, "description": "Sets the soft deadline. On the day it passes, every signer who can\nstill sign is reminded once. Independent of `expiresInDays`, which\nis the hard deadline.\n"}, "expiresInDays": {"type": "integer", "minimum": 1, "maximum": 30, "default": 14}}, "oneOf": [{"required": ["signers", "document"]}, {"required": ["signers", "container"]}, {"required": ["templateId"]}], "description": "Exactly one of `document` (a finished file) or `container` (several\nfiles composed into a new one) is required with `signers`, or\n`templateId` alone (v1.14.0). `title` is required unless\n`document.markdown` starts with a `# ` heading or a template gives it.\n", "additionalProperties": false}, "TemplateRolePrefill": {"type": "object", "description": "One role of a template, filled for one send (v1.14.0).", "properties": {"roleName": {"type": "string", "description": "A role name of the template, case ignored."}, "email": {"type": "string", "format": "email"}, "name": {"type": "string", "maxLength": 500}, "language": {"type": "string", "enum": ["lt", "en", "de", "et", "lv", "pl", "uk", "ru", "fr", "es", "it", "nl", "sv", "da", "nb", "fi"]}, "personalCode": {"type": "string", "pattern": "^(PNO(EE|LT)-)?[0-9]{11}$", "description": "Qualified templates only. Never stored on the template, never returned. The country is read as for a signer's `personalCode`."}, "methods": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/components/schemas/SigningMethod"}, "description": "Qualified templates only."}, "authentication": {"$ref": "#/components/schemas/ESignAuthentication"}}, "required": ["roleName"], "additionalProperties": false}, "TemplateRole": {"type": "object", "properties": {"roleName": {"type": "string", "maxLength": 80}, "name": {"type": ["string", "null"], "maxLength": 500}, "email": {"type": ["string", "null"], "format": "email", "description": "A saved signer, invited on every send unless the send names this role with another person."}, "language": {"type": ["string", "null"]}, "visibleSignature": {"description": "The placement of this role's signature, in the shape of a signer's\n`visibleSignature`, or null for the corner. Applied to qualified\nsigners; stored for simple e-signatures. Its sizes are those of\n`TemplateVisibleSignature` (v1.14.1).\n", "oneOf": [{"$ref": "#/components/schemas/TemplateVisibleSignature"}, {"type": "null"}]}}, "required": ["roleName"]}, "CreateTemplateRequest": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 255}, "document": {"type": "object", "description": "One PDF, through the same intake as a signing's `document`.", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}, "fileToken": {"type": "string", "format": "uuid"}, "markdown": {"type": "string"}, "url": {"type": "string", "format": "uri"}}, "additionalProperties": false}, "level": {"type": "string", "enum": ["qualified", "esign"], "default": "qualified"}, "signingOrder": {"type": "string", "enum": ["parallel", "sequential"], "default": "parallel"}, "expiresInDays": {"type": "integer", "minimum": 1, "maximum": 30}, "roles": {"type": "array", "minItems": 1, "maxItems": 20, "description": "In signing order. Role names are unique, case ignored.", "items": {"type": "object", "properties": {"roleName": {"type": "string", "minLength": 1, "maxLength": 80}, "name": {"type": "string", "maxLength": 500}, "email": {"type": "string", "format": "email"}, "language": {"type": "string", "enum": ["lt", "en", "de", "et", "lv", "pl", "uk", "ru", "fr", "es", "it", "nl", "sv", "da", "nb", "fi"]}, "visibleSignature": {"$ref": "#/components/schemas/VisibleSignature"}}, "required": ["roleName"], "additionalProperties": false}}}, "required": ["title", "document", "roles"], "additionalProperties": false}, "Template": {"type": "object", "properties": {"templateId": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "level": {"type": "string", "enum": ["qualified", "esign"]}, "signingOrder": {"type": "string", "enum": ["parallel", "sequential"]}, "expiresInDays": {"type": ["integer", "null"]}, "document": {"type": "object", "properties": {"name": {"type": "string"}, "sha256": {"type": "string"}, "bytes": {"type": "integer"}}}, "roles": {"type": "array", "items": {"$ref": "#/components/schemas/TemplateRole"}}, "createdAt": {"type": "string", "format": "date-time"}, "lastUsedAt": {"type": ["string", "null"], "format": "date-time"}, "useCount": {"type": "integer"}}}, "CreateBulkSendRequest": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 255, "description": "Every signing's title, unless a row sets its own. Defaults to the template's title."}, "rows": {"type": "array", "minItems": 1, "maxItems": 500, "items": {"type": "object", "properties": {"templateRoles": {"type": "array", "maxItems": 20, "items": {"$ref": "#/components/schemas/TemplateRolePrefill"}}, "externalId": {"type": "string", "maxLength": 120}, "title": {"type": "string", "maxLength": 255}}, "additionalProperties": false}}, "delivery": {"type": "string", "enum": ["link", "email"], "default": "link"}, "webhookUrl": {"type": "string", "format": "uri"}, "expiresInDays": {"type": "integer", "minimum": 1, "maximum": 30}, "softDeadlineInDays": {"type": "integer", "minimum": 1}}, "required": ["rows"], "additionalProperties": false}, "BulkSend": {"type": "object", "properties": {"bulkSendId": {"type": "string", "format": "uuid"}, "templateId": {"type": ["string", "null"], "format": "uuid"}, "title": {"type": "string"}, "status": {"type": "string", "enum": ["queued", "running", "finished"]}, "rowsTotal": {"type": "integer"}, "rowsSent": {"type": "integer"}, "rowsFailed": {"type": "integer"}, "createdAt": {"type": "string", "format": "date-time"}, "startedAt": {"type": ["string", "null"], "format": "date-time"}, "finishedAt": {"type": ["string", "null"], "format": "date-time"}, "rows": {"type": "array", "description": "One entry per row sent so far, in list order. Names and emails are not kept.", "items": {"type": "object", "properties": {"row": {"type": "integer", "minimum": 1}, "status": {"type": "string", "enum": ["sent", "failed"]}, "signingId": {"type": "string", "format": "uuid"}, "error": {"type": "string", "description": "The problem type slug the row was refused with, such as `payment-required`."}}}}}}, "SignerRequest": {"type": "object", "properties": {"role": {"type": "string", "enum": ["signer", "approver", "cc", "viewer"], "default": "signer", "description": "`signer` (default) signs the document. `approver` reviews and\napproves or declines via a guest link before any signing invitation\nis released; any decline retracts parked invitations and settles the\nsigning `declined` with zero signatures or billing (v1.30.0).\n`cc` receives the finished signed document copy by email once the\nsigning completes (attached up to 10 MiB, or a 30-day download link\nabove that, v1.30.0). `viewer` is recorded only and Tvarka sends\nthem nothing. At least one `signer` is required.\n"}, "group": {"type": "string", "minLength": 1, "maxLength": 64, "description": "Optional recipient group name (\"any 1 of N\", `role: signer` only,\nv1.30.0). Signers sharing a non-empty `group` share one execution\nslot; when any member signs, remaining active peers in that group\nare retracted (`cancelled`) and sequential workflows advance to the\nnext slot. In sequential signings, members of the same group must be\nlisted contiguously. Peers in the same group may share one\n`visibleSignature.field`.\n"}, "email": {"type": "string", "format": "email"}, "name": {"type": "string", "maxLength": 500}, "language": {"type": "string", "enum": ["lt", "en", "et", "lv", "pl", "uk", "ru", "de", "fr", "es", "it", "nl", "sv", "da", "nb", "fi"], "description": "Per signer, for their email and ceremony page. Left out, the signer gets the language of the company's country: lt for a Lithuanian company, de for a German one, and en where that language is not on the list. The list grew on 2026-09-14 and is additive: every value accepted before is still accepted, and the API answers an unknown one exactly as before."}, "personalCode": {"type": "string", "pattern": "^(PNO(EE|LT)-)?[0-9]{11}$", "description": "Optional identity lock: the personal code of the only person\nwho may sign. Eleven digits are read as a code of your\ncompany's country: Estonian for an Estonian company, Lithuanian\nfor every other. To name the country yourself, write `PNOEE-`\nor `PNOLT-` before the digits (v1.27.1). Tvarka stores a keyed\nhash and an encrypted value. The code is never returned, and a\ndifferent authenticated signer is refused. A locked signer who\nsigns with Mobile-ID types the phone number only.\n"}, "methods": {"type": "array", "minItems": 1, "uniqueItems": true, "default": ["nfc", "smart_id", "mobile_id"], "items": {"$ref": "#/components/schemas/SigningMethod"}, "description": "Per-signer allow-list. `nfc` uses the Tvarka Sign mobile app;\nSmart-ID and Mobile-ID use the hosted page or mobile app.\n"}, "signingPurpose": {"type": "string", "enum": ["signature", "confirmation", "visa", "registration"], "default": "signature", "description": "Immutable per-signer ADOC signed-metadata purpose. Non-default\nvalues require ADOC; omit for viewers. Approval uses confirmation.\nNon-default purposes require a native app that displays the purpose,\nor signing through the hosted browser ceremony.\nCovers a parallel signature over the container content and its\nsigned metadata; does not create a registration number/date or\ncounter-sign an earlier signature.\n"}, "visibleSignature": {"$ref": "#/components/schemas/VisibleSignature"}, "authentication": {"$ref": "#/components/schemas/ESignAuthentication"}}, "required": ["email"], "additionalProperties": false}, "ESignAuthentication": {"type": "object", "required": ["type"], "additionalProperties": false, "description": "`level: esign` only, refused on a qualified signing. One way to\nprotect this signer's link: `email_link` (default), `access_code`\nwith `code` (4 to 64 characters you give the signer yourself; Tvarka\nkeeps only a hash), or `sms` with `phoneNumber` (E.164; `422\nauthentication-unavailable` when SMS codes are not switched on, and\nnever a quiet fall back to the email link).\n", "properties": {"type": {"type": "string", "enum": ["email_link", "access_code", "sms"]}, "code": {"type": "string", "minLength": 4, "maxLength": 64}, "phoneNumber": {"type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$"}}}, "VisibleSignature": {"description": "Any workspace may place this signer's visible PDF stamp. Use\neither page coordinates in PDF points from the lower-left MediaBox\ncorner, or one existing unsigned signature field. The accepted value\nis immutable and returned on the signer. PDF only; field binding cannot\nbe combined with `document.flatten: true`.\n`page` is 1-based. Coordinates are finite PDF points (1/72 inch) in\nunrotated page space; x/y are offsets even when the MediaBox origin is\nnonzero. The whole box must fit MediaBox and CropBox. Minimum size is\n148 x 52 pt; placement requires /UserUnit: 1. A field must have\none usable visible widget, be unsigned and unlocked, and meet the\nsame geometry rules. Earlier field locks, ambiguous names and fields\nalready reserved for another signer are rejected. Explicit positions\ndo not become cascade anchors. Do not send this property for viewers.\nNo entitlement is needed (v1.13.1); the company logo and VIP\nwhitelabel are separate. Omit the property to use normal corner\nplacement; configured workspace branding still applies.\n", "examples": [{"page": 1, "x": 36, "y": 36, "width": 148, "height": 52}, {"field": "Sig_Vadovas"}], "oneOf": [{"type": "object", "properties": {"page": {"type": "integer", "minimum": 1}, "x": {"type": "number", "minimum": 0}, "y": {"type": "number", "minimum": 0}, "width": {"type": "number", "minimum": 148}, "height": {"type": "number", "minimum": 52}}, "required": ["page", "x", "y", "width", "height"], "additionalProperties": false}, {"type": "object", "properties": {"field": {"type": "string", "minLength": 1, "maxLength": 200}}, "required": ["field"], "additionalProperties": false}, {"type": "object", "description": "Smart anchor placement (v1.29.0): searches the PDF text for `anchor`\n(exact case-sensitive match first, diacritic-folded case-insensitive\nfallback) and places the stamp at the anchor baseline shifted by\noptional `offsetX` / `offsetY`. Supported on both `qualified` and\n`esign` signings and headless `pades` signatures.\n", "properties": {"anchor": {"type": "string", "minLength": 1, "maxLength": 120}, "offsetX": {"type": "number", "default": 0}, "offsetY": {"type": "number", "default": 0}, "width": {"type": "number", "minimum": 148, "default": 148}, "height": {"type": "number", "minimum": 52, "default": 52}, "occurrence": {"default": "first", "oneOf": [{"type": "string", "enum": ["first", "last"]}, {"type": "integer", "minimum": 1, "maximum": 100}]}}, "required": ["anchor"], "additionalProperties": false}]}, "TemplateVisibleSignature": {"description": "A box saved on a template role, and the box a signer gets from it\n(v1.14.1). The shape of `VisibleSignature`. The sizes are those of\nthe template's level, the sizes the Tvarka Sign app saves it with:\nat least the default qualified stamp (103.18 x 35.72 pt) or the\ndefault e-signature mark (119.06 x 45.64 pt), and at most three\ntimes that. When a qualified template is sent, the box is checked\nby these sizes and must fit the PDF. A box sent to `POST /v1/templates` is\na box sent in a request, so it keeps the `VisibleSignature` rules,\n148 x 52 pt at least. A field binding keeps the field rules of\n`VisibleSignature`.\n", "examples": [{"page": 1, "x": 60, "y": 120, "width": 103.18, "height": 35.72}, {"field": "Sig_Vadovas"}], "oneOf": [{"type": "object", "properties": {"page": {"type": "integer", "minimum": 1}, "x": {"type": "number", "minimum": 0}, "y": {"type": "number", "minimum": 0}, "width": {"type": "number", "exclusiveMinimum": 0}, "height": {"type": "number", "exclusiveMinimum": 0}}, "required": ["page", "x", "y", "width", "height"], "additionalProperties": false}, {"type": "object", "properties": {"field": {"type": "string", "minLength": 1, "maxLength": 200}}, "required": ["field"], "additionalProperties": false}, {"type": "object", "properties": {"anchor": {"type": "string", "minLength": 1, "maxLength": 120}, "offsetX": {"type": "number", "default": 0}, "offsetY": {"type": "number", "default": 0}, "width": {"type": "number", "exclusiveMinimum": 0}, "height": {"type": "number", "exclusiveMinimum": 0}, "occurrence": {"default": "first", "oneOf": [{"type": "string", "enum": ["first", "last"]}, {"type": "integer", "minimum": 1, "maximum": 100}]}}, "required": ["anchor"], "additionalProperties": false}]}, "Me": {"type": "object", "properties": {"workspace": {"type": "object", "properties": {"name": {"type": "string"}, "country": {"type": "string", "description": "ISO 3166-1 alpha-2."}}, "required": ["name", "country"]}, "environment": {"type": "string", "enum": ["production", "sandbox"]}, "user": {"type": "object", "properties": {"email": {"type": "string", "format": "email"}}, "required": ["email"]}}, "required": ["workspace", "environment", "user"]}, "WebhookEventName": {"type": "string", "enum": ["signing.approver_approved", "signing.approver_declined", "signing.signer_signed", "signing.signer_declined", "signing.signer_failed", "signing.completed", "signing.declined", "signing.cancelled", "signing.expired", "signing.failed", "form_request.opened", "form_request.submitted", "form_request.completed", "form_request.cancelled", "form_request.expired", "form_request.failed"]}, "FormLegalBasis": {"type": "object", "properties": {"title": {"type": "string"}, "article": {"type": "string"}, "url": {"type": "string", "format": "uri"}}}, "FormField": {"type": "object", "properties": {"key": {"type": "string", "description": "The semantic identifier, for example person.given_name."}, "type": {"type": "string", "enum": ["text", "number", "email", "phone", "date", "dropdown", "radio", "checkbox", "attachment", "barcode", "drawing"]}, "label": {"type": "string"}, "required": {"type": "boolean"}, "group": {"type": "string", "description": "Fields with one group share one value."}, "options": {"type": "array", "items": {"type": "string"}}, "preset": {"type": "string", "enum": ["countries"]}}, "required": ["key", "type", "label", "required"]}, "FormTemplateVersion": {"type": "object", "properties": {"templateId": {"type": "string", "format": "uuid"}, "templateVersionId": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "kind": {"type": "string", "enum": ["own", "statutory"]}, "version": {"type": "integer"}, "publishedAt": {"type": ["string", "null"], "format": "date-time"}, "legalBasis": {"type": "array", "items": {"$ref": "#/components/schemas/FormLegalBasis"}}, "approvingAct": {"oneOf": [{"$ref": "#/components/schemas/FormLegalBasis"}, {"type": "null"}]}, "asksFiller": {"type": "boolean", "description": "The person is asked whether a parent or guardian fills the forms."}, "fields": {"type": "array", "items": {"$ref": "#/components/schemas/FormField"}}}, "required": ["templateId", "templateVersionId", "title", "kind", "version", "legalBasis", "fields"]}, "CreateFormRequest": {"type": "object", "additionalProperties": false, "properties": {"templateVersionIds": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "string", "format": "uuid"}}, "channel": {"type": "string", "enum": ["remote", "kiosk"], "default": "remote", "description": "`kiosk` (v1.17.0) needs no phone or email and sends no link; send the request to a tablet with `POST /v1/kiosk-sessions` (`product: forms`)."}, "respondent": {"type": "object", "additionalProperties": false, "properties": {"name": {"type": "string", "maxLength": 200}, "phone": {"type": "string", "description": "International form, for example +37060000000."}, "email": {"type": "string", "format": "email"}}}, "visitAt": {"type": "string", "format": "date-time"}, "sendAt": {"type": "string", "format": "date-time"}, "sendNow": {"type": "boolean"}, "expiresAt": {"type": "string", "format": "date-time"}, "prefill": {"type": "object", "description": "Values by semantic identifier.", "additionalProperties": true}, "personalCode": {"type": "string", "description": "The Lithuanian personal code of the person who signs."}, "language": {"type": "string"}, "emailSignedCopy": {"type": "boolean", "default": true}, "externalId": {"type": "string", "maxLength": 200}, "webhookUrl": {"type": "string", "format": "uri"}}, "required": ["templateVersionIds"]}, "UpdateFormRequest": {"type": "object", "additionalProperties": false, "properties": {"visitAt": {"type": "string", "format": "date-time"}, "sendAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": "string", "format": "date-time"}, "resend": {"type": "boolean"}, "cancel": {"type": "boolean"}}}, "FormRequestStatus": {"type": "string", "enum": ["scheduled", "sent", "opened", "in_progress", "submitted", "staff_pending", "completed", "expired", "cancelled", "failed"]}, "FormRequest": {"type": "object", "properties": {"formRequestId": {"type": "string", "format": "uuid"}, "reference": {"type": "string"}, "status": {"$ref": "#/components/schemas/FormRequestStatus"}, "channel": {"type": "string", "enum": ["remote", "walk_in", "kiosk"]}, "externalId": {"type": ["string", "null"]}, "templateVersionIds": {"type": "array", "items": {"type": "string", "format": "uuid"}}, "respondent": {"type": "object", "properties": {"name": {"type": ["string", "null"]}, "phone": {"type": ["string", "null"]}, "email": {"type": ["string", "null"]}}}, "visitAt": {"type": ["string", "null"], "format": "date-time"}, "sendAt": {"type": ["string", "null"], "format": "date-time"}, "expiresAt": {"type": ["string", "null"], "format": "date-time"}, "sentAt": {"type": ["string", "null"], "format": "date-time"}, "openedAt": {"type": ["string", "null"], "format": "date-time"}, "submittedAt": {"type": ["string", "null"], "format": "date-time"}, "completedAt": {"type": ["string", "null"], "format": "date-time"}, "createdAt": {"type": "string", "format": "date-time"}, "filler": {"type": "object", "properties": {"who": {"type": "string", "enum": ["subject", "guardian"]}, "name": {"type": ["string", "null"]}, "relation": {"type": ["string", "null"]}}}, "events": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string"}, "actor": {"type": "string"}, "at": {"type": "string", "format": "date-time"}}}}, "values": {"type": "object", "description": "Present once submitted. Values by semantic identifier.", "additionalProperties": true}, "document": {"type": "object", "properties": {"url": {"type": "string", "format": "uri"}, "sha256": {"type": "string"}}}, "signers": {"type": "array", "description": "Who signed, in order (v1.18.0): the name at the mark (\"Name\nSurname, position\" for a staff member) and when. Present once the\nperson has signed (`staff_pending`) and on completion.\n", "items": {"type": "object", "properties": {"name": {"type": "string"}, "signedAt": {"type": ["string", "null"], "format": "date-time"}}}}}, "required": ["formRequestId", "reference", "status", "channel", "templateVersionIds", "events", "createdAt"]}, "FormAttachment": {"type": "object", "properties": {"attachmentId": {"type": "string", "format": "uuid"}, "field": {"type": "string"}, "filename": {"type": "string"}, "contentType": {"type": "string"}, "bytes": {"type": "integer"}, "sha256": {"type": "string"}}}, "FormRequestEvent": {"type": "object", "properties": {"event": {"type": "string", "enum": ["form_request.opened", "form_request.submitted", "form_request.completed", "form_request.cancelled", "form_request.expired", "form_request.failed"]}, "eventId": {"type": "string"}, "webhookId": {"type": "string", "format": "uuid"}, "formRequestId": {"type": "string", "format": "uuid"}, "reference": {"type": "string"}, "status": {"$ref": "#/components/schemas/FormRequestStatus"}, "occurredAt": {"type": "string", "format": "date-time"}, "visitAt": {"type": ["string", "null"], "format": "date-time"}, "externalId": {"type": "string"}, "values": {"type": "object", "additionalProperties": true}, "document": {"type": "object", "properties": {"url": {"type": "string", "format": "uri"}, "sha256": {"type": "string"}}}, "evidence": {"type": "object", "properties": {"url": {"type": "string", "format": "uri"}}}}, "required": ["event", "eventId", "formRequestId", "reference", "status", "occurredAt"]}, "CreateWebhookSubscription": {"type": "object", "properties": {"url": {"type": "string", "format": "uri", "maxLength": 500}, "events": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/components/schemas/WebhookEventName"}}}, "required": ["url", "events"], "additionalProperties": false}, "WebhookSubscription": {"type": "object", "properties": {"webhookId": {"type": "string", "format": "uuid"}, "url": {"type": "string", "format": "uri"}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookEventName"}}, "createdAt": {"type": "string", "format": "date-time"}}, "required": ["webhookId", "url", "events", "createdAt"]}, "WebhookSubscriptionList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookSubscription"}}}, "required": ["data"]}, "WebhookDelivery": {"type": "object", "properties": {"deliveryId": {"type": "string", "format": "uuid"}, "channel": {"type": "string", "enum": ["sign", "sign_sig", "sign_hook", "sign_form", "sign_ts"]}, "event": {"type": "string"}, "resourceId": {"type": "string", "format": "uuid"}, "signingId": {"type": ["string", "null"], "format": "uuid"}, "signerId": {"type": ["string", "null"], "format": "uuid"}, "callbackUrl": {"type": "string", "format": "uri"}, "status": {"type": "string", "enum": ["pending", "delivered", "exhausted", "discarded"]}, "attempts": {"type": "integer", "minimum": 0}, "lastError": {"type": ["string", "null"]}, "discardReason": {"type": ["string", "null"]}, "createdAt": {"type": "string", "format": "date-time"}, "deliveredAt": {"type": ["string", "null"], "format": "date-time"}, "nextAttemptAt": {"type": ["string", "null"], "format": "date-time"}, "exhaustedAt": {"type": ["string", "null"], "format": "date-time"}, "discardedAt": {"type": ["string", "null"], "format": "date-time"}, "payload": {"type": ["object", "string", "null"], "additionalProperties": true}}, "required": ["deliveryId", "channel", "event", "resourceId", "callbackUrl", "status", "attempts", "createdAt"]}, "WebhookDeliveryList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookDelivery"}}, "hasMore": {"type": "boolean"}}, "required": ["data", "hasMore"]}, "SigningList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Signing"}}, "hasMore": {"type": "boolean"}, "nextCursor": {"type": ["string", "null"], "format": "uuid"}}, "required": ["data", "hasMore", "nextCursor"]}, "Signing": {"type": "object", "properties": {"signingId": {"type": "string", "format": "uuid"}, "status": {"$ref": "#/components/schemas/SigningStatus"}, "level": {"type": "string", "enum": ["qualified", "esign"]}, "processingStage": {"type": "string", "enum": ["awaiting_approvers", "awaiting_signers", "finalizing"], "description": "While `pending`: `awaiting_approvers` while pre-sign approvers are\nopen, `awaiting_signers` while signers can still sign, or\n`finalizing` once every signer slot is satisfied and the file is\nbeing sealed (a simple e-signature's document timestamp).\n"}, "title": {"type": "string"}, "delivery": {"type": "string", "enum": ["link", "email"]}, "signingOrder": {"type": "string", "enum": ["parallel", "sequential"], "description": "`sequential` releases one signer at a time in the order they were\nposted. The signers who are waiting hold a ceremony link that\nanswers 404 until their turn, so the ordering is enforced rather\nthan merely unsent. A decline stops the workflow at the\ndecliner's turn: the signing settles `declined` and the signers\nstill waiting are cancelled.\n"}, "softDeadlineAt": {"type": ["string", "null"], "format": "date-time", "description": "The date the signing is wanted by, as opposed to `expiresAt`,\nwhich is the date it dies on. Nothing expires here; it is when the\none automatic reminder goes out.\n"}, "externalId": {"type": ["string", "null"]}, "templateId": {"type": "string", "format": "uuid", "description": "Present when the signing was sent from a template (v1.14.0)."}, "embedOrigin": {"type": "string", "format": "uri", "description": "Present when the signing permits iframe embedding on a registered HTTPS origin (v1.29.0)."}, "createdAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": ["string", "null"], "format": "date-time"}, "completedAt": {"type": ["string", "null"], "format": "date-time"}, "completionMode": {"type": ["string", "null"], "enum": ["qes_ceremony", "esign_ceremony", "sandbox_simulation", null], "description": "`qes_ceremony` means human eID signing. `esign_ceremony` means a\ncompleted simple e-signature. `sandbox_simulation`\nexercises lifecycle/webhook integration and creates no\nsignature; its artifact is flagged `sandbox: true`.\n"}, "erasedAt": {"type": ["string", "null"], "format": "date-time"}, "detail": {"type": "string", "description": "Present when the status needs a sentence of explanation."}, "signers": {"type": "array", "items": {"$ref": "#/components/schemas/Signer"}}, "document": {"$ref": "#/components/schemas/SignedDocument"}, "authority": {"type": "object", "description": "Present when the signing named the company its signers sign for\n(MCP `entityCode`, v1.19.0). Once the signing completes, each\nsigner's personal code from their qualified signature is matched\nagainst the vadovas recorded in JAR. `recordedRole` is `vadovas`\nor null. Billed once, as a Tvarka Due Diligence JAR extract.\n", "properties": {"entityCode": {"type": "string"}, "register": {"type": "string", "enum": ["JAR"]}, "status": {"type": "string", "enum": ["pending", "checked", "unavailable"]}, "checkedAt": {"type": "string", "format": "date-time"}, "entityFound": {"type": "boolean"}, "sandbox": {"type": "boolean"}, "signers": {"type": "array", "items": {"type": "object", "properties": {"email": {"type": "string"}, "recordedRole": {"type": ["string", "null"], "enum": ["vadovas", null]}, "detail": {"type": "string", "enum": ["identity_unavailable"]}}}}}}, "evidence": {"type": "object", "description": "A completed simple e-signature (`level: esign`).", "properties": {"available": {"type": "boolean", "description": "False once erased."}, "referenceCode": {"type": "string"}, "verificationUrl": {"type": "string", "format": "uri"}, "separateSummary": {"type": "boolean"}, "sealedAt": {"type": ["string", "null"], "format": "date-time"}, "sandbox": {"type": "boolean"}, "validation": {"type": "object", "properties": {"status": {"type": "string", "enum": ["notApplicable"]}}}}}}}, "Signer": {"type": "object", "properties": {"signerId": {"type": "string", "format": "uuid"}, "role": {"type": "string", "enum": ["signer", "approver", "cc", "viewer"], "description": "`signer` signs the document; `approver` reviews and approves before\nsigning begins; `cc` receives the finished signed document copy by\nemail once signing completes; `viewer` is recorded only and Tvarka\nsends them nothing. At least one signer is required.\n"}, "group": {"type": "string", "maxLength": 64, "description": "Recipient group name when this signer belongs to an \"any 1 of N\" group."}, "email": {"type": ["string", "null"], "format": "email"}, "name": {"type": ["string", "null"]}, "language": {"type": "string", "enum": ["lt", "en", "et", "lv", "pl", "uk", "ru", "de", "fr", "es", "it", "nl", "sv", "da", "nb", "fi"]}, "status": {"$ref": "#/components/schemas/SignerStatus"}, "ceremonyUrl": {"type": "string", "format": "uri", "description": "Present only while this signer (`role: signer`) can still sign. A\nfinished or retracted invitation has no live URL.\n"}, "approvalUrl": {"type": "string", "format": "uri", "description": "Present only while this pre-sign approver (`role: approver`) is\n`pending`. Cleared once approved, declined, cancelled, or expired.\n"}, "approvedAt": {"type": ["string", "null"], "format": "date-time"}, "ccNotifiedAt": {"type": ["string", "null"], "format": "date-time"}, "signedAt": {"type": ["string", "null"], "format": "date-time"}, "declinedAt": {"type": ["string", "null"], "format": "date-time"}, "declineReason": {"type": "string"}, "methodsAllowed": {"type": "array", "items": {"$ref": "#/components/schemas/SigningMethod"}}, "actualMethod": {"oneOf": [{"$ref": "#/components/schemas/SigningMethod"}, {"type": "null"}], "description": "Present after a real signature; contains no identity data."}, "identityLocked": {"type": "boolean"}, "authentication": {"type": "object", "description": "`level: esign` signers: the protection type only, never the code.", "properties": {"type": {"type": "string", "enum": ["email_link", "access_code", "sms"]}}}, "signingPurpose": {"type": ["string", "null"], "enum": ["signature", "confirmation", "visa", "registration", null], "description": "Accepted immutable purpose; null for a viewer."}, "visibleSignature": {"description": "The accepted placement, or null. A signer of a signing sent from\na template carries the role's saved box (`TemplateVisibleSignature`,\nv1.14.1).\n", "anyOf": [{"$ref": "#/components/schemas/VisibleSignature"}, {"$ref": "#/components/schemas/TemplateVisibleSignature"}, {"type": "null"}]}, "identityMatched": {"type": ["boolean", "null"], "description": "True only after a locked signer completes the real ceremony."}, "simulatedAt": {"type": ["string", "null"], "format": "date-time"}, "emailStatus": {"type": "string", "enum": ["not_requested", "pending", "accepted", "failed", "cancelled", "unknown"], "description": "Initial invitation email state. Accepted means the email backend\naccepted the message, not inbox delivery. Unknown denotes legacy\nbest-effort delivery whose outcome was not recorded. Sequential\nsigners stay not_requested until their turn is released.\n"}, "emailAcceptedAt": {"type": ["string", "null"], "format": "date-time"}}}, "Batch": {"type": "object", "properties": {"batchId": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "externalId": {"type": ["string", "null"]}, "createdAt": {"type": "string", "format": "date-time"}, "signings": {"type": "array", "items": {"$ref": "#/components/schemas/Signing"}}}}, "StoredFile": {"type": "object", "properties": {"fileToken": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "mediaType": {"type": "string"}, "sha256": {"type": "string"}, "bytes": {"type": "integer"}, "createdAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": "string", "format": "date-time", "description": "An unreferenced upload is not kept forever just because nobody\ndeleted it. Re-upload after this, or post the bytes inline.\n"}, "usedCount": {"type": "integer", "description": "How many signings have copied these bytes."}}}, "Comment": {"type": "object", "properties": {"commentId": {"type": "string", "format": "uuid"}, "author": {"type": "string", "enum": ["client", "tvarka"]}, "authorLabel": {"type": ["string", "null"]}, "body": {"type": "string"}, "createdAt": {"type": "string", "format": "date-time"}}}, "SignedDocument": {"type": "object", "description": "The newest signed output. Absent until somebody signs, except on a\nsandbox simulation, where it describes the unsigned artifact.\n", "properties": {"sha256": {"type": "string"}, "bytes": {"type": "integer"}, "mimeType": {"type": "string"}, "sandbox": {"type": "boolean", "description": "Present and true only on a sandbox simulation. The bytes are a\nreal file to which no signature was added.\n"}, "signed": {"type": "boolean", "description": "Present and false only on a sandbox simulation. Absent on a real\nsigning, where the output is signed by definition.\n"}}}, "SigningStatus": {"type": "string", "enum": ["pending", "completed", "declined", "cancelled", "expired", "failed"], "description": "`pending` - at least one signer can still sign.\n`completed` - every signer signed.\n`declined` - somebody declined and nobody else can still sign.\n`expired` - the window closed first.\n`cancelled` - you retracted it.\n`failed` - the signing could not be prepared.\n"}, "SignerStatus": {"type": "string", "enum": ["pending", "signed", "approved", "declined", "cancelled", "expired", "failed", "simulated", "waiting", "recorded"], "description": "`waiting` - a sequential signer/approver whose turn has not come, or a\nsigner parked while pre-sign approvers review; their link answers 404\nuntil released.\n`approved` - a pre-sign approver who approved the document.\n`failed` - the signer's requested PDF stamp could not be prepared.\n`recorded` - a `cc` or `viewer` party. Never blocks completion.\n"}, "SigningMethod": {"type": "string", "enum": ["nfc", "smart_id", "mobile_id"], "description": "The orchestration methods. For direct LT ATK reader, USB, raw CAdES\nand lower-level NFC integration, use the ATK API.\n"}, "ProblemFieldError": {"type": "object", "description": "One rejected field.", "properties": {"code": {"type": "string", "description": "Stable signing refusal code on a document-not-signable response."}, "pointer": {"type": "string", "description": "RFC 6901 JSON Pointer into the request body, for example\n`/signers/0/email` or `/container/files/2/content`.\n"}, "detail": {"type": "string"}}, "required": ["pointer", "detail"]}, "Problem": {"type": "object", "description": "RFC 9457.", "properties": {"final": {"type": "boolean", "description": "True for a definitive document-not-signable refusal."}, "type": {"type": "string", "format": "uri"}, "title": {"type": "string"}, "status": {"type": "integer"}, "detail": {"type": "string"}, "errors": {"type": "array", "description": "Present on `validation-failed`, and on the single-fault problems\nthat name a field. Request-body validation collects rather than\nfailing fast, so a caller who got three fields wrong learns all\nthree from one response.\n", "items": {"$ref": "#/components/schemas/ProblemFieldError"}}, "recoveryUrl": {"type": "string", "format": "uri-reference", "description": "Present on the payment-required refusal when a web page exists\nthat fixes it: the tenant's payment setup, reached with an\nordinary browser login. Show it to your operator; it is not an\nAPI endpoint.\n"}, "billingContext": {"type": "object", "description": "Present on order-time payment-required refusals. Identifies the\ncompany fixed to the API key, regardless of browser workspace.\nPayment arrangements require an active company administrator (manager or managing employee who may manage payments).\n", "required": ["workspaceId", "companyCode", "companyName", "canManageBilling"], "properties": {"workspaceId": {"type": "string", "format": "uuid"}, "companyCode": {"type": "string"}, "companyName": {"type": "string"}, "canManageBilling": {"type": "boolean"}}}}}}}}