---
title: "Create a signing"
method: POST
path: "/v1/signings"
tags: ["Signings"]
---

# Create a signing

`POST /v1/signings`

## Request

- Base URL: `https://sign-api.tvarka.pro`
- URL: `https://sign-api.tvarka.pro/v1/signings`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`
  - OAuth 2 (authorization code, authorization URL `https://sign-api.tvarka.pro/oauth/authorize`, token URL `https://sign-api.tvarka.pro/oauth/token`, scopes: `sign.read`, `sign.signings`)

Stores the document, opens one ceremony per signer, and returns the
ceremony URLs (or emails them, with `delivery: email`).
`level: esign` asks for a simple e-signature (v1.11.0); see the
description above.

All signers sign the same document and are unordered: whoever opens
their link first signs first, and each subsequent signer signs the
output the previous one produced. Two signers never sign at the same
moment - the ceremony serializes them.

## Headers

- `Idempotency-Key` string

## Request body

- union: Exactly one of `document` (a finished file) or `container` (several files composed into a new one) is required with `signers`, or `templateId` alone (v1.14.0). `title` is required unless `document.markdown` starts with a `# ` heading or a template gives it.
  - object
    - `title` string: Shown to signers on the ceremony page and in their email.
    - `document` object, required
      - `name` string: Filename with extension. The extension selects the family: `.pdf`; `.docx`, `.doc`, `.odt`, `.rtf`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.odp`, `.txt`, `.jpg`, `.jpeg` and `.png`, converted to PDF/A-2b and signed as a PDF (v1.9.0); `.asice`/`.sce`/`.bdoc` to countersign an existing appendable ASiC-E; `.adoc`/`.bedoc`/`.cedoc`/`.gedoc`/ `.ggedoc` to countersign a signed ADOC-family container. For containers the extension only decides that we look inside - the container's own mimetype member decides what it is. `.mdoc` is refused: an MDOC takes a first signature only.
      - `content` string, byte: Base64-encoded bytes, up to 15 MiB decoded. Provide exactly one of `content`, `fileToken`, `markdown` or `url`.
      - `fileToken` string, uuid: A reusable upload from `POST /v1/files`, referenced instead of carrying the bytes again. The bytes are copied into the signing at creation, so purging the file later never reaches into a signing that already used it. Provide exactly one of `content`, `fileToken`, `markdown` or `url`.
      - `markdown` string: The document as Markdown (CommonMark with tables and strikethrough). Tvarka renders it to an A4 PDF/A-2b and signs that PDF. Raw HTML is shown as text and nothing remote is loaded, so the PDF is exactly the text. The first `# ` heading becomes the title when `title` is omitted, and `name` defaults to that title.
      - `url` string, uri: A public HTTPS link Tvarka downloads the document from: a PDF, a convertible Office file or image (converted to PDF/A-2b, v1.9.0), an appendable ASiC-E or a signed ADOC-family container. Private and loopback addresses are refused, each redirect (up to three) is re-checked, and the download is bounded by the document size limit and 20 seconds. `name` defaults to the last path segment.
      - `flatten` boolean: PDF only. Draw every form field's appearance into page content and drop the AcroForm, so what a reader sees cannot depend on a viewer's form handling. Fails closed: if any widget has no appearance stream Tvarka can draw faithfully, nothing is flattened and the response names those fields. Signing a live AcroForm without this is perfectly valid - the signature still detects any later edit. Limits per request (shared across batch documents): 1,000 pages, 5,000 widgets, 10,000 annotations, 10,000 field-tree nodes and field depth 64. Complexity is checked before cloning. A cooperative 20-second budget checks between PDF operations; it does not interrupt a parser or writer call. Refusal returns 400 with the flatten error pointer. Split the batch or flatten before upload.
    - `container` object: Compose a NEW container from several files and sign that, instead of posting one finished document. Mutually exclusive with `document`; exactly one of the two is required.
      - `format` 'asice' | 'adoc', required: `asice` takes PDFs only. `adoc` is the Lithuanian ADOC-V1.0 package and takes `.pdf` and `.xlsx`. The first file is the main document; the rest are appendices.
      - `files` object[], required
        - `name` string, required
        - `content` string, byte, required
    - `level` 'qualified' | 'esign': Fixed at creation (v1.11.0). `qualified`: each signer signs with their eID. `esign`: a simple e-signature on the Tvarka page, one PDF, signers with `email`, `name`, `language` and `authentication` only.
    - `templateId` string, uuid: Send a saved template (v1.14.0). The document, `level`, `signingOrder` and each role's placement come from the template, so `document`, `container`, `signers`, `level` and `signingOrder` are refused beside it. `title` defaults to the template's title and `expiresInDays` to its expiry.
    - `templateRoles` TemplateRolePrefill[]: With `templateId`: who signs each role. A role with a saved signer may be left out; every other role needs an entry with an email. A fault in the template's saved data points at `/templateId`.
      - `roleName` string, required: A role name of the template, case ignored.
      - `email` string, email
      - `name` string
      - `language` 'lt' | 'en' | 'de' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi'
      - `personalCode` string: Qualified templates only. Never stored on the template, never returned.
      - `methods` SigningMethod[]: Qualified templates only.
      - `authentication` ESignAuthentication: `level: esign` only, refused on a qualified signing. One way to protect this signer's link: `email_link` (default), `access_code` with `code` (4 to 64 characters you give the signer yourself; Tvarka keeps only a hash), or `sms` with `phoneNumber` (E.164; `422 authentication-unavailable` when SMS codes are not switched on, and never a quiet fall back to the email link).
        - `type` 'email_link' | 'access_code' | 'sms', required
        - `code` string
        - `phoneNumber` string
    - `signers` SignerRequest[], required: Participants in input order, which is the release order for a sequential signing. Each email may appear once.
      - `role` 'signer' | 'viewer': A `viewer` is recorded but never invited, never gets a ceremony link, and never holds up completion. Tvarka sends them nothing. At least one signer is required.
      - `email` string, email, required
      - `name` string
      - `language` 'lt' | 'en' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'de' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi': 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` string: Optional Lithuanian identity lock. Tvarka stores a keyed hash and encrypted value, never returns the code, and refuses a different authenticated signer.
      - `methods` SigningMethod[]: Per-signer allow-list. `nfc` uses the Tvarka Sign mobile app; Smart-ID and Mobile-ID use the hosted page or mobile app.
      - `signingPurpose` 'signature' | 'confirmation' | 'visa' | 'registration': Immutable per-signer ADOC signed-metadata purpose. Non-default values require ADOC; omit for viewers. Approval uses confirmation. Non-default purposes require a native app that displays the purpose, or signing through the hosted browser ceremony. Covers a parallel signature over the container content and its signed metadata; does not create a registration number/date or counter-sign an earlier signature.
      - `visibleSignature` union: Any workspace may place this signer's visible PDF stamp. Use either page coordinates in PDF points from the lower-left MediaBox corner, or one existing unsigned signature field. The accepted value is immutable and returned on the signer. PDF only; field binding cannot be combined with `document.flatten: true`. `page` is 1-based. Coordinates are finite PDF points (1/72 inch) in unrotated page space; x/y are offsets even when the MediaBox origin is nonzero. The whole box must fit MediaBox and CropBox. Minimum size is 148 x 52 pt; placement requires /UserUnit: 1. A field must have one usable visible widget, be unsigned and unlocked, and meet the same geometry rules. Earlier field locks, ambiguous names and fields already reserved for another signer are rejected. Explicit positions do not become cascade anchors. Do not send this property for viewers. No entitlement is needed (v1.13.1); the company logo and VIP whitelabel are separate. Omit the property to use normal corner placement; configured workspace branding still applies.
        - object
          - `page` integer, required
          - `x` number, required
          - `y` number, required
          - `width` number, required
          - `height` number, required
        - object
          - `field` string, required
      - `authentication` ESignAuthentication: `level: esign` only, refused on a qualified signing. One way to protect this signer's link: `email_link` (default), `access_code` with `code` (4 to 64 characters you give the signer yourself; Tvarka keeps only a hash), or `sms` with `phoneNumber` (E.164; `422 authentication-unavailable` when SMS codes are not switched on, and never a quiet fall back to the email link).
        - `type` 'email_link' | 'access_code' | 'sms', required
        - `code` string
        - `phoneNumber` string
    - `delivery` 'link' | 'email': `link` returns a `ceremonyUrl` per signer for you to deliver. `email` has Tvarka email each signer in your entity's name.
    - `returnUrl` string, uri: 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` string: Random per-browser-session correlation value; required with returnUrl. Compare it on return. Never put personal data or secrets here.
    - `webhookUrl` string, uri: Public HTTPS URL for signing events. Optional.
    - `externalId` string: Your own reference, echoed on every response and webhook.
    - `signingOrder` 'parallel' | 'sequential'
    - `softDeadlineInDays` integer: Sets the soft deadline. On the day it passes, every signer who can still sign is reminded once. Independent of `expiresInDays`, which is the hard deadline.
    - `expiresInDays` integer
  - object
    - `title` string: Shown to signers on the ceremony page and in their email.
    - `document` object
      - `name` string: Filename with extension. The extension selects the family: `.pdf`; `.docx`, `.doc`, `.odt`, `.rtf`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.odp`, `.txt`, `.jpg`, `.jpeg` and `.png`, converted to PDF/A-2b and signed as a PDF (v1.9.0); `.asice`/`.sce`/`.bdoc` to countersign an existing appendable ASiC-E; `.adoc`/`.bedoc`/`.cedoc`/`.gedoc`/ `.ggedoc` to countersign a signed ADOC-family container. For containers the extension only decides that we look inside - the container's own mimetype member decides what it is. `.mdoc` is refused: an MDOC takes a first signature only.
      - `content` string, byte: Base64-encoded bytes, up to 15 MiB decoded. Provide exactly one of `content`, `fileToken`, `markdown` or `url`.
      - `fileToken` string, uuid: A reusable upload from `POST /v1/files`, referenced instead of carrying the bytes again. The bytes are copied into the signing at creation, so purging the file later never reaches into a signing that already used it. Provide exactly one of `content`, `fileToken`, `markdown` or `url`.
      - `markdown` string: The document as Markdown (CommonMark with tables and strikethrough). Tvarka renders it to an A4 PDF/A-2b and signs that PDF. Raw HTML is shown as text and nothing remote is loaded, so the PDF is exactly the text. The first `# ` heading becomes the title when `title` is omitted, and `name` defaults to that title.
      - `url` string, uri: A public HTTPS link Tvarka downloads the document from: a PDF, a convertible Office file or image (converted to PDF/A-2b, v1.9.0), an appendable ASiC-E or a signed ADOC-family container. Private and loopback addresses are refused, each redirect (up to three) is re-checked, and the download is bounded by the document size limit and 20 seconds. `name` defaults to the last path segment.
      - `flatten` boolean: PDF only. Draw every form field's appearance into page content and drop the AcroForm, so what a reader sees cannot depend on a viewer's form handling. Fails closed: if any widget has no appearance stream Tvarka can draw faithfully, nothing is flattened and the response names those fields. Signing a live AcroForm without this is perfectly valid - the signature still detects any later edit. Limits per request (shared across batch documents): 1,000 pages, 5,000 widgets, 10,000 annotations, 10,000 field-tree nodes and field depth 64. Complexity is checked before cloning. A cooperative 20-second budget checks between PDF operations; it does not interrupt a parser or writer call. Refusal returns 400 with the flatten error pointer. Split the batch or flatten before upload.
    - `container` object, required: Compose a NEW container from several files and sign that, instead of posting one finished document. Mutually exclusive with `document`; exactly one of the two is required.
      - `format` 'asice' | 'adoc', required: `asice` takes PDFs only. `adoc` is the Lithuanian ADOC-V1.0 package and takes `.pdf` and `.xlsx`. The first file is the main document; the rest are appendices.
      - `files` object[], required
        - `name` string, required
        - `content` string, byte, required
    - `level` 'qualified' | 'esign': Fixed at creation (v1.11.0). `qualified`: each signer signs with their eID. `esign`: a simple e-signature on the Tvarka page, one PDF, signers with `email`, `name`, `language` and `authentication` only.
    - `templateId` string, uuid: Send a saved template (v1.14.0). The document, `level`, `signingOrder` and each role's placement come from the template, so `document`, `container`, `signers`, `level` and `signingOrder` are refused beside it. `title` defaults to the template's title and `expiresInDays` to its expiry.
    - `templateRoles` TemplateRolePrefill[]: With `templateId`: who signs each role. A role with a saved signer may be left out; every other role needs an entry with an email. A fault in the template's saved data points at `/templateId`.
      - `roleName` string, required: A role name of the template, case ignored.
      - `email` string, email
      - `name` string
      - `language` 'lt' | 'en' | 'de' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi'
      - `personalCode` string: Qualified templates only. Never stored on the template, never returned.
      - `methods` SigningMethod[]: Qualified templates only.
      - `authentication` ESignAuthentication: `level: esign` only, refused on a qualified signing. One way to protect this signer's link: `email_link` (default), `access_code` with `code` (4 to 64 characters you give the signer yourself; Tvarka keeps only a hash), or `sms` with `phoneNumber` (E.164; `422 authentication-unavailable` when SMS codes are not switched on, and never a quiet fall back to the email link).
        - `type` 'email_link' | 'access_code' | 'sms', required
        - `code` string
        - `phoneNumber` string
    - `signers` SignerRequest[], required: Participants in input order, which is the release order for a sequential signing. Each email may appear once.
      - `role` 'signer' | 'viewer': A `viewer` is recorded but never invited, never gets a ceremony link, and never holds up completion. Tvarka sends them nothing. At least one signer is required.
      - `email` string, email, required
      - `name` string
      - `language` 'lt' | 'en' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'de' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi': 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` string: Optional Lithuanian identity lock. Tvarka stores a keyed hash and encrypted value, never returns the code, and refuses a different authenticated signer.
      - `methods` SigningMethod[]: Per-signer allow-list. `nfc` uses the Tvarka Sign mobile app; Smart-ID and Mobile-ID use the hosted page or mobile app.
      - `signingPurpose` 'signature' | 'confirmation' | 'visa' | 'registration': Immutable per-signer ADOC signed-metadata purpose. Non-default values require ADOC; omit for viewers. Approval uses confirmation. Non-default purposes require a native app that displays the purpose, or signing through the hosted browser ceremony. Covers a parallel signature over the container content and its signed metadata; does not create a registration number/date or counter-sign an earlier signature.
      - `visibleSignature` union: Any workspace may place this signer's visible PDF stamp. Use either page coordinates in PDF points from the lower-left MediaBox corner, or one existing unsigned signature field. The accepted value is immutable and returned on the signer. PDF only; field binding cannot be combined with `document.flatten: true`. `page` is 1-based. Coordinates are finite PDF points (1/72 inch) in unrotated page space; x/y are offsets even when the MediaBox origin is nonzero. The whole box must fit MediaBox and CropBox. Minimum size is 148 x 52 pt; placement requires /UserUnit: 1. A field must have one usable visible widget, be unsigned and unlocked, and meet the same geometry rules. Earlier field locks, ambiguous names and fields already reserved for another signer are rejected. Explicit positions do not become cascade anchors. Do not send this property for viewers. No entitlement is needed (v1.13.1); the company logo and VIP whitelabel are separate. Omit the property to use normal corner placement; configured workspace branding still applies.
        - object
          - `page` integer, required
          - `x` number, required
          - `y` number, required
          - `width` number, required
          - `height` number, required
        - object
          - `field` string, required
      - `authentication` ESignAuthentication: `level: esign` only, refused on a qualified signing. One way to protect this signer's link: `email_link` (default), `access_code` with `code` (4 to 64 characters you give the signer yourself; Tvarka keeps only a hash), or `sms` with `phoneNumber` (E.164; `422 authentication-unavailable` when SMS codes are not switched on, and never a quiet fall back to the email link).
        - `type` 'email_link' | 'access_code' | 'sms', required
        - `code` string
        - `phoneNumber` string
    - `delivery` 'link' | 'email': `link` returns a `ceremonyUrl` per signer for you to deliver. `email` has Tvarka email each signer in your entity's name.
    - `returnUrl` string, uri: 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` string: Random per-browser-session correlation value; required with returnUrl. Compare it on return. Never put personal data or secrets here.
    - `webhookUrl` string, uri: Public HTTPS URL for signing events. Optional.
    - `externalId` string: Your own reference, echoed on every response and webhook.
    - `signingOrder` 'parallel' | 'sequential'
    - `softDeadlineInDays` integer: Sets the soft deadline. On the day it passes, every signer who can still sign is reminded once. Independent of `expiresInDays`, which is the hard deadline.
    - `expiresInDays` integer
  - object
    - `title` string: Shown to signers on the ceremony page and in their email.
    - `document` object
      - `name` string: Filename with extension. The extension selects the family: `.pdf`; `.docx`, `.doc`, `.odt`, `.rtf`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.odp`, `.txt`, `.jpg`, `.jpeg` and `.png`, converted to PDF/A-2b and signed as a PDF (v1.9.0); `.asice`/`.sce`/`.bdoc` to countersign an existing appendable ASiC-E; `.adoc`/`.bedoc`/`.cedoc`/`.gedoc`/ `.ggedoc` to countersign a signed ADOC-family container. For containers the extension only decides that we look inside - the container's own mimetype member decides what it is. `.mdoc` is refused: an MDOC takes a first signature only.
      - `content` string, byte: Base64-encoded bytes, up to 15 MiB decoded. Provide exactly one of `content`, `fileToken`, `markdown` or `url`.
      - `fileToken` string, uuid: A reusable upload from `POST /v1/files`, referenced instead of carrying the bytes again. The bytes are copied into the signing at creation, so purging the file later never reaches into a signing that already used it. Provide exactly one of `content`, `fileToken`, `markdown` or `url`.
      - `markdown` string: The document as Markdown (CommonMark with tables and strikethrough). Tvarka renders it to an A4 PDF/A-2b and signs that PDF. Raw HTML is shown as text and nothing remote is loaded, so the PDF is exactly the text. The first `# ` heading becomes the title when `title` is omitted, and `name` defaults to that title.
      - `url` string, uri: A public HTTPS link Tvarka downloads the document from: a PDF, a convertible Office file or image (converted to PDF/A-2b, v1.9.0), an appendable ASiC-E or a signed ADOC-family container. Private and loopback addresses are refused, each redirect (up to three) is re-checked, and the download is bounded by the document size limit and 20 seconds. `name` defaults to the last path segment.
      - `flatten` boolean: PDF only. Draw every form field's appearance into page content and drop the AcroForm, so what a reader sees cannot depend on a viewer's form handling. Fails closed: if any widget has no appearance stream Tvarka can draw faithfully, nothing is flattened and the response names those fields. Signing a live AcroForm without this is perfectly valid - the signature still detects any later edit. Limits per request (shared across batch documents): 1,000 pages, 5,000 widgets, 10,000 annotations, 10,000 field-tree nodes and field depth 64. Complexity is checked before cloning. A cooperative 20-second budget checks between PDF operations; it does not interrupt a parser or writer call. Refusal returns 400 with the flatten error pointer. Split the batch or flatten before upload.
    - `container` object: Compose a NEW container from several files and sign that, instead of posting one finished document. Mutually exclusive with `document`; exactly one of the two is required.
      - `format` 'asice' | 'adoc', required: `asice` takes PDFs only. `adoc` is the Lithuanian ADOC-V1.0 package and takes `.pdf` and `.xlsx`. The first file is the main document; the rest are appendices.
      - `files` object[], required
        - `name` string, required
        - `content` string, byte, required
    - `level` 'qualified' | 'esign': Fixed at creation (v1.11.0). `qualified`: each signer signs with their eID. `esign`: a simple e-signature on the Tvarka page, one PDF, signers with `email`, `name`, `language` and `authentication` only.
    - `templateId` string, uuid, required: Send a saved template (v1.14.0). The document, `level`, `signingOrder` and each role's placement come from the template, so `document`, `container`, `signers`, `level` and `signingOrder` are refused beside it. `title` defaults to the template's title and `expiresInDays` to its expiry.
    - `templateRoles` TemplateRolePrefill[]: With `templateId`: who signs each role. A role with a saved signer may be left out; every other role needs an entry with an email. A fault in the template's saved data points at `/templateId`.
      - `roleName` string, required: A role name of the template, case ignored.
      - `email` string, email
      - `name` string
      - `language` 'lt' | 'en' | 'de' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi'
      - `personalCode` string: Qualified templates only. Never stored on the template, never returned.
      - `methods` SigningMethod[]: Qualified templates only.
      - `authentication` ESignAuthentication: `level: esign` only, refused on a qualified signing. One way to protect this signer's link: `email_link` (default), `access_code` with `code` (4 to 64 characters you give the signer yourself; Tvarka keeps only a hash), or `sms` with `phoneNumber` (E.164; `422 authentication-unavailable` when SMS codes are not switched on, and never a quiet fall back to the email link).
        - `type` 'email_link' | 'access_code' | 'sms', required
        - `code` string
        - `phoneNumber` string
    - `signers` SignerRequest[]: Participants in input order, which is the release order for a sequential signing. Each email may appear once.
      - `role` 'signer' | 'viewer': A `viewer` is recorded but never invited, never gets a ceremony link, and never holds up completion. Tvarka sends them nothing. At least one signer is required.
      - `email` string, email, required
      - `name` string
      - `language` 'lt' | 'en' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'de' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi': 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` string: Optional Lithuanian identity lock. Tvarka stores a keyed hash and encrypted value, never returns the code, and refuses a different authenticated signer.
      - `methods` SigningMethod[]: Per-signer allow-list. `nfc` uses the Tvarka Sign mobile app; Smart-ID and Mobile-ID use the hosted page or mobile app.
      - `signingPurpose` 'signature' | 'confirmation' | 'visa' | 'registration': Immutable per-signer ADOC signed-metadata purpose. Non-default values require ADOC; omit for viewers. Approval uses confirmation. Non-default purposes require a native app that displays the purpose, or signing through the hosted browser ceremony. Covers a parallel signature over the container content and its signed metadata; does not create a registration number/date or counter-sign an earlier signature.
      - `visibleSignature` union: Any workspace may place this signer's visible PDF stamp. Use either page coordinates in PDF points from the lower-left MediaBox corner, or one existing unsigned signature field. The accepted value is immutable and returned on the signer. PDF only; field binding cannot be combined with `document.flatten: true`. `page` is 1-based. Coordinates are finite PDF points (1/72 inch) in unrotated page space; x/y are offsets even when the MediaBox origin is nonzero. The whole box must fit MediaBox and CropBox. Minimum size is 148 x 52 pt; placement requires /UserUnit: 1. A field must have one usable visible widget, be unsigned and unlocked, and meet the same geometry rules. Earlier field locks, ambiguous names and fields already reserved for another signer are rejected. Explicit positions do not become cascade anchors. Do not send this property for viewers. No entitlement is needed (v1.13.1); the company logo and VIP whitelabel are separate. Omit the property to use normal corner placement; configured workspace branding still applies.
        - object
          - `page` integer, required
          - `x` number, required
          - `y` number, required
          - `width` number, required
          - `height` number, required
        - object
          - `field` string, required
      - `authentication` ESignAuthentication: `level: esign` only, refused on a qualified signing. One way to protect this signer's link: `email_link` (default), `access_code` with `code` (4 to 64 characters you give the signer yourself; Tvarka keeps only a hash), or `sms` with `phoneNumber` (E.164; `422 authentication-unavailable` when SMS codes are not switched on, and never a quiet fall back to the email link).
        - `type` 'email_link' | 'access_code' | 'sms', required
        - `code` string
        - `phoneNumber` string
    - `delivery` 'link' | 'email': `link` returns a `ceremonyUrl` per signer for you to deliver. `email` has Tvarka email each signer in your entity's name.
    - `returnUrl` string, uri: 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` string: Random per-browser-session correlation value; required with returnUrl. Compare it on return. Never put personal data or secrets here.
    - `webhookUrl` string, uri: Public HTTPS URL for signing events. Optional.
    - `externalId` string: Your own reference, echoed on every response and webhook.
    - `signingOrder` 'parallel' | 'sequential'
    - `softDeadlineInDays` integer: Sets the soft deadline. On the day it passes, every signer who can still sign is reminded once. Independent of `expiresInDays`, which is the hard deadline.
    - `expiresInDays` integer

## Response `201`

The signing was created and every signer has a live ceremony.

- Signing
  - `signingId` string, uuid
  - `status` 'pending' | 'completed' | 'declined' | 'cancelled' | 'expired' | 'failed': `pending` - at least one signer can still sign. `completed` - every signer signed. `declined` - somebody declined and nobody else can still sign. `expired` - the window closed first. `cancelled` - you retracted it. `failed` - the signing could not be prepared.
  - `level` 'qualified' | 'esign'
  - `processingStage` 'awaiting_signers' | 'finalizing': While `pending`: `finalizing` once every signer signed and the file is being sealed (a simple e-signature's document timestamp).
  - `title` string
  - `delivery` 'link' | 'email'
  - `signingOrder` 'parallel' | 'sequential': `sequential` releases one signer at a time in the order they were posted. The signers who are waiting hold a ceremony link that answers 404 until their turn, so the ordering is enforced rather than merely unsent. A decline stops the workflow at the decliner's turn: the signing settles `declined` and the signers still waiting are cancelled.
  - `softDeadlineAt` string, date-time, nullable: The date the signing is wanted by, as opposed to `expiresAt`, which is the date it dies on. Nothing expires here; it is when the one automatic reminder goes out.
  - `externalId` string, nullable
  - `templateId` string, uuid: Present when the signing was sent from a template (v1.14.0).
  - `createdAt` string, date-time
  - `expiresAt` string, date-time, nullable
  - `completedAt` string, date-time, nullable
  - `completionMode` 'qes_ceremony' | 'esign_ceremony' | 'sandbox_simulation' | 'null', nullable: `qes_ceremony` means human eID signing. `esign_ceremony` means a completed simple e-signature. `sandbox_simulation` exercises lifecycle/webhook integration and creates no signature; its artifact is flagged `sandbox: true`.
  - `erasedAt` string, date-time, nullable
  - `detail` string: Present when the status needs a sentence of explanation.
  - `signers` Signer[]
    - `signerId` string, uuid
    - `role` 'signer' | 'viewer': A `viewer` is a recorded non-signing party: no invitation is raised, no ceremony link exists, and they never hold up completion. Tvarka sends them nothing - you hold the webhook and the download, and distribute. At least one signer is required.
    - `email` string, email, nullable
    - `name` string, nullable
    - `language` 'lt' | 'en' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'de' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi'
    - `status` 'pending' | 'signed' | 'declined' | 'cancelled' | 'expired' | 'failed' | 'simulated' | 'waiting' | 'recorded': `waiting` - a sequential signer whose turn has not come; their ceremony link answers 404 until it does. `failed` - the signer's requested PDF stamp could not be prepared. `recorded` - a viewer. Never invited, never blocks completion.
    - `ceremonyUrl` string, uri: Present only while this signer can still sign. A finished or retracted invitation has no live URL.
    - `signedAt` string, date-time, nullable
    - `declinedAt` string, date-time, nullable
    - `declineReason` string
    - `methodsAllowed` SigningMethod[]
    - `actualMethod` 'nfc' | 'smart_id' | 'mobile_id': The orchestration methods. For direct LT ATK reader, USB, raw CAdES and lower-level NFC integration, use the ATK API.
    - `identityLocked` boolean
    - `authentication` object: `level: esign` signers: the protection type only, never the code.
      - `type` 'email_link' | 'access_code' | 'sms'
    - `signingPurpose` 'signature' | 'confirmation' | 'visa' | 'registration' | 'null', nullable: Accepted immutable purpose; null for a viewer.
    - `visibleSignature` union: The accepted placement, or null. A signer of a signing sent from a template carries the role's saved box (`TemplateVisibleSignature`, v1.14.1).
      - union: Any workspace may place this signer's visible PDF stamp. Use either page coordinates in PDF points from the lower-left MediaBox corner, or one existing unsigned signature field. The accepted value is immutable and returned on the signer. PDF only; field binding cannot be combined with `document.flatten: true`. `page` is 1-based. Coordinates are finite PDF points (1/72 inch) in unrotated page space; x/y are offsets even when the MediaBox origin is nonzero. The whole box must fit MediaBox and CropBox. Minimum size is 148 x 52 pt; placement requires /UserUnit: 1. A field must have one usable visible widget, be unsigned and unlocked, and meet the same geometry rules. Earlier field locks, ambiguous names and fields already reserved for another signer are rejected. Explicit positions do not become cascade anchors. Do not send this property for viewers. No entitlement is needed (v1.13.1); the company logo and VIP whitelabel are separate. Omit the property to use normal corner placement; configured workspace branding still applies.
        - object
          - `page` integer, required
          - `x` number, required
          - `y` number, required
          - `width` number, required
          - `height` number, required
        - object
          - `field` string, required
      - union: A box saved on a template role, and the box a signer gets from it (v1.14.1). The shape of `VisibleSignature`. The sizes are those of the template's level, the sizes the Tvarka Sign app saves it with: at least the default qualified stamp (103.18 x 35.72 pt) or the default e-signature mark (119.06 x 45.64 pt), and at most three times that. When a qualified template is sent, the box is checked by these sizes and must fit the PDF. A box sent to `POST /v1/templates` is a box sent in a request, so it keeps the `VisibleSignature` rules, 148 x 52 pt at least. A field binding keeps the field rules of `VisibleSignature`.
        - object
          - `page` integer, required
          - `x` number, required
          - `y` number, required
          - `width` number, required
          - `height` number, required
        - object
          - `field` string, required
    - `identityMatched` boolean, nullable: True only after a locked signer completes the real ceremony.
    - `simulatedAt` string, date-time, nullable
    - `emailStatus` 'not_requested' | 'pending' | 'accepted' | 'failed' | 'cancelled' | 'unknown': Initial invitation email state. Accepted means the email backend accepted the message, not inbox delivery. Unknown denotes legacy best-effort delivery whose outcome was not recorded. Sequential signers stay not_requested until their turn is released.
    - `emailAcceptedAt` string, date-time, nullable
  - `document` SignedDocument: The newest signed output. Absent until somebody signs, except on a sandbox simulation, where it describes the unsigned artifact.
    - `sha256` string
    - `bytes` integer
    - `mimeType` string
    - `sandbox` boolean: Present and true only on a sandbox simulation. The bytes are a real file to which no signature was added.
    - `signed` boolean: Present and false only on a sandbox simulation. Absent on a real signing, where the output is signed by definition.
  - `evidence` object: A completed simple e-signature (`level: esign`).
    - `available` boolean: False once erased.
    - `referenceCode` string
    - `verificationUrl` string, uri
    - `separateSummary` boolean
    - `sealedAt` string, date-time, nullable
    - `sandbox` boolean
    - `validation` object
      - `status` 'notApplicable'

## Other responses

- `400`: An RFC 9457 problem document.
- `401`: An RFC 9457 problem document.
- `402`: The tenant cannot pay for the ceremony: no payment rail, an overdue invoice, or a tripped usage ceiling. Nothing was created and nobody was invited. `recoveryUrl` names the web page where the tenant can fix it.
- `403`: An RFC 9457 problem document.
- `409`: The idempotency key conflicts, is pending, or has an erased or expired result.
- `413`: An RFC 9457 problem document.
- `422`: A well-formed request for a container that cannot take another signature - unsigned, already finalized, or structurally unsound. Not billed.
- `429`: An RFC 9457 problem document.
- `503`: An RFC 9457 problem document.

---

[API](https://skmtc.dev/tvarka/apis/tvarka-sign-api.md) · [All operations](https://skmtc.dev/tvarka/apis/tvarka-sign-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tvarka/apis/tvarka-sign-api/revisions/e3fdd995c013?raw)