Tvarka Sign

Send documents for simple e-signatures or qualified signatures under eIDAS, track each signing and download the signed file with its evidence. Remote server at https://sign-api.tvarka.pro/mcp, sign in by OAuth or API key, paid per signed document.

Gehosteter MCP-Server

npx add-mcp 'https://sign-api.tvarka.pro/mcp'

Installiert in Claude Code, Codex, Cursor und mehr

Dokumentation

Tvarka Sign API

Version 1.30.0

A document goes out to its signers. Each signer signs in a hosted page or in your own screen. The signed file comes back with its evidence.

Send your first document

One POST to /v1/signings with a document and a list of signers starts a signing. A webhook reports each step until the signing is complete.

BASE=https://sign-api.tvarka.pro
# TVARKA_KEY holds your API key.
curl -sS "$BASE/v1/signings" \
  -H "Authorization: Bearer $TVARKA_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: first-signing-1" \
  -d '{"title": "Service agreement", "document": {"markdown": "# Service agreement\n\nThe work starts on 1 December."}, "delivery": "link", "signers": [{"email": "alex@example.com", "name": "Alex Example"}]}'

Machine channel for Tvarka Sign: post a document and a list of signers. With level: esign each signer reads the PDF and signs on the Tvarka page, with no eID (simple e-signatures). With level: qualified, the default, Tvarka runs its ordinary qualified signing ceremony for each of them. The signer follows the confirmation steps for their method (signing confirmations). Or sign a hash, a PDF, an XML, a JSON or any file from your own application with Smart-ID or Mobile-ID, with no hosted page (headless signatures). A signature is always a person using their own eID.

Choose your integration

  • Simple e-signatures: REST /v1/signings and MCP with level: esign. Each signer reads the PDF and signs on the Tvarka page; one charge per completed document (simple e-signatures).
  • Templates, lists, forms and tablets: send a saved template, or one template to a list of up to 500 people (templates). Ask a person to fill and sign forms on their phone (forms). Send a PDF to a tablet at your desk for a drawn signature (tablet sessions).
  • Timestamps and web page capture: REST /v1/timestamps and MCP seal a file, a hash or a captured web page, also from a chosen place (timestamps).
  • Hosted qualified signing: REST /v1/signings and MCP prepare documents, invite signers, track progress and return signed originals.
  • Headless qualified signing: REST /v1/signatures lets your application show the verification code for Smart-ID or Mobile-ID, or a Smart-ID QR code or app link. It requires the workspace headless entitlement.
  • Google Workspace Add-on: send Google Docs and Google Drive files for signature directly from the sidebar (Google Workspace Marketplace, details).
  • Team signing: use the Tvarka Sign web application. Its signed-in client endpoints use workspace sessions; they are a separate contract from this Bearer-key REST/MCP API.
  • Card-native integration: use the ATK developer API with a card-driving client and ATK credentials.
  • Company data and identification packages: use the Tvarka Due Diligence API and its dedicated key.

For ADOC, each signer may set signingPurpose to signature (default), confirmation (approval), visa or registration. The accepted value is immutable and appears in the signed metadata and the invitation. Non-default purposes are rejected for PDF and ASiC-E; viewers cannot set a purpose. This is parallel signing of the container content and metadata, not creation of a registration record or a counter-signature over an earlier signature.

The OpenAPI below defines the supported public request fields. For hosted signing, CreateSigningRequest takes level: qualified (the default) or esign.

Simple e-signatures

Send "level": "esign" to POST /v1/signings, or to MCP send_document and request_signatures. Each signer reads the PDF and signs on the Tvarka page, with no eID. One PDF per signing (Office files and images are converted first), one or more signers, parallel or sequential, link or email delivery. A signer has email, name, language and one authentication: email_link (default), access_code with a code you give the signer yourself, or sms with a phoneNumber when SMS codes are switched on for your workspace. Tvarka keeps only a hash of the code and never returns it.

{"level": "esign", "title": "Service agreement",
 "document": {"fileToken": "<uploaded-file-token>"},
 "signers": [{"email": "alex@example.com", "name": "Alex Example"},
             {"email": "sam@example.com", "authentication": {"type": "access_code", "code": "<out-of-band-code>"}}],
 "signingOrder": "sequential", "delivery": "link"}

The signers are fixed when the signing is created: to change them, cancel and create a new one. Once everybody has signed, Tvarka seals the file with a document timestamp; meanwhile the signing is pending with processingStage: finalizing. When it is completed, GET /v1/signings/{signingId}/document returns the sealed PDF and GET /v1/signings/{signingId}/evidence the evidence ZIP (the sealed PDF, the signing summary and the timestamp tokens). The signing names its evidence.referenceCode and a public verificationUrl. One charge per completed document, however many signers; nothing is charged for a signing that does not complete.

Signing confirmations

Hosted and headless Smart-ID/Mobile-ID signing share the certificate lookup and signing sequence. A known signing certificate needs one signing PIN. Where the configured certificate service supplies the certificate without a PIN, first use also needs one signing PIN; a new Smart-ID account may first need approval in the app. If the flow instead needs a certificate-capture confirmation, that comes before the document-signing confirmation: two PINs in total. Follow the current verification code, rather than assuming a fixed number of prompts.

For headless signing, render nextAction: show verificationCode for compare_code, ask the signer to confirm their Smart-ID account for confirm_certificate, show qrLink as a QR code for scan_qr, open appLink for open_app, otherwise wait. A transition from authentication to signing can emit signature.confirmation_required with the new code and the same nextAction.revision; replace the displayed code. Hosted pages handle this for you. The Smart-ID QR/app-link journey opens the Smart-ID app for the signer; follow the hosted page and app prompts. Card/USB and NFC signing use the card's signing PIN through the supported local client; any required identity step is presented in that client.

REST quickstart · Webhook verification · Recent changes

Custom PDF stamps

Exact PDF placement is included for every workspace, in Tvarka Sign and the API. A company logo in the stamp is a premium feature that Tvarka activates. VIP whitelabel is a separate premium feature for changing or removing the vendor line. Standard clients keep the default Tvarka line; the Tekstas po parašu controls are hidden without VIP access. Contact info@tvarka.pro for activation.

Configure your workspace

The active company Vadovas opens Users and access → Parašo išvaizda in the cloud browser. Choose the company workspace, upload its logo, preview, then save. The tab remains visible with disabled controls until activation, even when the developer API is disabled. Tvarka operators manage the logo and VIP entitlements in Administravimas → Funkcijos; a customer cannot activate either entitlement themselves.

  • PNG up to 1 MB; longest side 200-2000 px, neither side above 2000 px, aspect ratio between 1:3 and 3:1. Transparency is retained and the logo is fitted proportionally into the stamp.
  • VIP clients may keep the default vendor line, enter up to 32 printable characters that fit the stamp, or omit the line. Signer name, time and purpose remain visible.
  • Preview is private and unsigned. Saving or restoring the default appearance affects new signing documents and orders; it does not rewrite an accepted appearance. Logo references are retained for existing snapshots.

These are browser settings, not new bearer-key REST endpoints or MCP tools. Do not add logo, tagline or entitlement fields to signing requests.

Place an API signer's stamp

Add visibleSignature to each signing party. Choose exactly one of these signer objects (replace the sample email). A headless pades signature takes the same object, or true for the default corner, at the top level of POST /v1/signatures.

{
  "email": "signer@example.com",
  "visibleSignature": {"page": 1, "x": 36, "y": 36, "width": 148, "height": 52}
}
{
  "email": "signer@example.com",
  "visibleSignature": {"field": "Sig_Vadovas"}
}
  • page is 1-based. Coordinates are PDF points (1/72 inch), offset from the unrotated page MediaBox's lower-left corner. Width is at least 148 pt and height at least 52 pt; all numbers must be finite. The rectangle must fit both MediaBox and CropBox. Placement requires /UserUnit: 1.
  • A field name is fully qualified and at most 200 printable characters. It must identify one empty, visible, unlocked signature field with one usable widget of sufficient size. Earlier signatures' field locks are respected; signed, hidden, ambiguous and already-reserved fields are rejected.
  • Smart anchors (v1.29.0): pass {"anchor": "[[SIG_1]]", "offsetX": 0, "offsetY": 0, "width": 148, "height": 52, "occurrence": "first"} to locate text inside the PDF (exact case-sensitive match first, diacritic-folded case-insensitive fallback) and place the signature box at that anchor's baseline. offsetX, offsetY, width, height and occurrence ("first", "last" or 1–100) are optional.
  • PDF signing parties (both qualified and esign) only: containers and viewers cannot use placement. Field binding cannot be combined with document.flatten: true.
  • The same shape works with POST /v1/signings, POST /v1/signings/{signingId}/signers, POST /v1/batches and MCP request_signatures. Batch placement must be valid for every document before invitations are sent.
  • The accepted normalized value is immutable and returned in signer status. Omit it to use normal corner/cascade placement; workspace branding still applies. Explicit positions never silently move or fall back to a corner. You are responsible for avoiding overlaps between explicit rectangles.

Shared appearance, separate placements

Each API order freezes its effective logo and vendor line on acceptance, including later signers, retries and idempotent replays. Editing or resetting workspace branding, or revoking logo/VIP access, does not change that snapshot. After VIP revocation, new snapshots use the default Tvarka line.

Regular Sign uses the same workspace branding for remote, USB/NFC and invited signing. Its Mano parašo vieta editor lets a user preview and save their own qualified PDF signature's coordinates or existing field; API-owned placement remains controlled by the API order. Sign freezes branding when signing, pairing, an internal-signature job or an invitation first begins; signed outputs retain the source snapshot. Internal electronic signatures keep their non-qualified label and existing overlay position. Personal signing and non-PDF containers retain their existing behavior.

Preview and handle failures

Sandbox /simulate completion renders the requested placements and snapshotted branding, including default-corner signers, branding-only orders and MCP orders from vault documents. The artifact is conspicuously unsigned. Already-signed input stays byte-identical and receives no stamp preview.

  • 400 validation-failed: invalid placement, geometry, field or flatten combination; use the returned JSON pointers to correct the request.
  • 422 stamp-preparation-failed: a sandbox preview cannot be prepared.
  • During a real ceremony, placement and logo are checked again against the locked current PDF. If the requested stamp can no longer be prepared, signer and order fail terminally; webhooks emit signing.signer_failed and signing.failed. Remaining invitations and pending work are retracted; already collected signatures remain intact. A provider outage alone does not trigger this stamp-failure cleanup.

Same-tab signing and automatic return

Send the signer to their ceremonyUrl in the current browser tab. Add returnUrl and a random, session-bound returnState (16-128 URL-safe ASCII characters) when creating the signing or batch. Register your exact HTTPS return URL first: in the Tvarka Sign app open Settings, then API settings, and save it under Return address.

After signing or declining, the browser returns automatically with state, signingId, signerId and result. Results are signed, declined, cancelled, expired, simulated (sandbox), or returned when the signer chooses Return to your application. Returning early leaves the signing request open. Match state to the browser session and retrieve the signing through your backend or verify its webhook; URL parameters are never proof of a signature. One signer's completion need not complete the order.

The hosted page retains its anti-framing protection. An iframe allows the surrounding page to overlay signing controls; same-tab navigation keeps document review in Tvarka.

Workflow

Signers are parallel by default. signingOrder: sequential releases them one at a time in the order you posted them, and the signers who are waiting hold a link that answers 404 until their turn, so the order is enforced and not merely unsent. A decline stops the workflow at the decliner's turn: the signing settles declined and the signers still waiting are cancelled. A signer added to a sequential signing joins the end of the queue. A signer may carry role: viewer: a recorded party who is never invited, never blocks completion and is sent nothing - you hold the webhook and the download.

Two deadlines. expiresInDays is the hard one, the date the signing dies. softDeadlineInDays is the date it is wanted by: nothing expires, but every signer who can still sign is reminded once on the day it passes.

Batches and reusable files

Upload documents up to 100 MB (100,000,000 bytes) with multipart POST /v1/files: one binary part named file, retaining its filename extension. Use the returned fileToken in document.fileToken. Existing JSON/base64 uploads remain available up to 15 MiB decoded. Signed outputs may grow as signature evidence is added.

POST /v1/files stores a document once and returns a fileToken a later signing may reference instead of carrying base64 again. The bytes are copied into each signing, so deleting a file never reaches into one that already used it.

POST /v1/batches raises one signing per document for one set of parties. It is a grouping, not a single signing act: every document keeps its own ceremony and its own signature, because the ID card produces one signature per document. It buys one call and one identifier to poll, not one PIN for many documents. Combined source bytes and combined prepared bytes each have a 100,000,000-byte limit. Repeated file tokens count repeatedly. Known oversized batches are refused before reading stored files; remote downloads and stored-file reads use the remaining source-byte allowance. Aggregate overflow returns HTTP 413; remote-download refusals return HTTP 400 with the document URL pointer. No signing is created on refusal.

POST /v1/signings/{signingId}/comments keeps your own notes on a signing. Comments are not shown to signers.

Templates and bulk send

A template is a saved PDF with its signer roles, the signature level, the order and, per role, the visibleSignature placement (v1.14.0). POST /v1/templates saves one from the same document intake a signing takes; templates saved in the Tvarka Sign app are listed by GET /v1/templates too. A role with an email has a saved signer, invited on every send.

POST /v1/signings with templateId sends it. Name each role in templateRoles ([{"roleName": "Klientas", "email": "...", "name": "..."}]); a role with a saved signer may be left out. The document, level, order and placement come from the template, so document, signers, level and signingOrder are refused beside it. A fault points into what you sent (/templateRoles/0/email), or at /templateId when the template's saved data fails. The signing carries templateId.

A role's saved box is checked by the sizes of the template's level, the sizes the Tvarka Sign app saves it with: at least the default stamp (103.18 x 35.72 pt) or e-signature mark (119.06 x 45.64 pt), at most three times that (v1.14.1). A box sent in a request, POST /v1/templates included, keeps the 148 x 52 pt minimum.

POST /v1/templates/{templateId}/bulk-sends sends one signing per row, up to 500 rows. Every row is checked first, so one bad row refuses the list and nothing is created. Then the rows go out in the background and GET /v1/bulk-sends/{bulkSendId} reports each row's signingId or error. A row cannot carry a personal code or an access code; send those signings one by one. Each signing is billed as a single one. MCP: list_templates, then send_from_template.

Long-term signatures

POST /v1/signings/{signingId}/archive raises signed output to a long-term level: PDF to PAdES-B-LT, ASiC-E to XAdES-LT, embedding the chain and revocation evidence so the signature still validates once the certificate has expired. ASiC-E signing already reaches XAdES-LT on its own, so this is for output that arrived at T. ADOC is refused by name: ADOC-V1.0 specifies XAdES-T and its validators expect it.

REST sandbox quickstart

Use a POSIX shell with curl, jq and Python 3. Set TVARKA_SIGN_KEY in your local environment to an existing tsk_test_ key. Paid API calls work only when there is enough money on the company's balance. Add money to the balance in Billing before your first call. Questions are answered at info@tvarka.pro. Sign, Due Diligence and ATK keys are separate.

Use a small synthetic unsigned PDF named example.pdf. This flow uploads it, creates a link-delivered request without sending an invitation email, simulates completion, polls and verifies the downloaded artifact. For a simple e-signature, add "level": "esign" to create.json. The signers then read and sign on the Tvarka page with no eID (simple e-signatures). Run each create step once; retain its JSON body, key and returned ID before retrying.

set -eu
# Use an existing sandbox key. Never put a production key in this example.
case "$TVARKA_SIGN_KEY" in tsk_test_*) ;; *) echo "Use a sandbox key"; exit 1;; esac
BASE=https://sign-api.tvarka.pro
# Save any small, unsigned PDF as example.pdf before running this block.
# Keep this idempotency key and create.json for a retry of THIS signing.
IDEMPOTENCY_KEY="quickstart-$(python3 -c 'import uuid; print(uuid.uuid4())')"
TOKEN=$(curl --fail-with-body -sS "$BASE/v1/files" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" \
  -F 'file=@example.pdf;type=application/pdf' | jq -er '.fileToken')
jq -n --arg token "$TOKEN" '{title:"Sandbox example",document:{fileToken:$token},delivery:"link",signers:[{email:"reader@example.test",name:"Example Reader",language:"en"}]}' > create.json
curl --fail-with-body -sS "$BASE/v1/signings" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" --data-binary @create.json > signing.json
SIGNING=$(jq -er '.signingId' signing.json)
curl --fail-with-body -sS "$BASE/v1/signings/$SIGNING/simulate" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -d '{"action":"complete"}' > simulated.json
curl --fail-with-body -sS "$BASE/v1/signings/$SIGNING" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" > result.json
jq -e '.status == "completed" and .completionMode == "sandbox_simulation" and .document.sandbox == true and .document.signed == false' result.json
curl --fail-with-body -sS "$BASE/v1/signings/$SIGNING/document" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -D artifact.headers -o sandbox-result.pdf
python3 - <<'PY'
import hashlib, json
from pathlib import Path
result = json.loads(Path('result.json').read_text())
assert 'x-tvarka-sandbox: simulated-artifact-no-signature' in Path('artifact.headers').read_text().lower()
assert hashlib.sha256(Path('sandbox-result.pdf').read_bytes()).hexdigest() == result['document']['sha256']
print('Downloaded sandbox artifact; hash matches. No signature was created.')
PY

Multipart upload accepts up to 100,000,000 bytes; inline/base64 requests accept up to 15 MiB of decoded document bytes. Reuse fileToken for large files. Sandbox completion exercises the lifecycle and download path; it creates no qualified signature. Production uses the real signer ceremony instead of /simulate.

Headless sandbox example

Using the same sandbox environment, this example supplies a synthetic identity and digest. In production, hash the exact document and display the corresponding content to the signer; renderHash records what you showed. Every production key signs headless at once.

# Sandbox only; set HEADLESS_REQUEST_KEY once and retain it for retries.
HEADLESS_REQUEST_KEY="headless-$(python3 -c 'import uuid; print(uuid.uuid4())')"
DIGEST=$(python3 -c 'import hashlib,base64; print(base64.b64encode(hashlib.sha256(b"Synthetic document").digest()).decode())')
jq -n --arg hash "$DIGEST" '{method:"smart_id",signer:{personalCode:"39001010011"},document:{name:"Synthetic document",profile:"cades-detached",hash:{algorithm:"sha256",value:$hash}},display:{text:"Sandbox signing"},renderHash:{algorithm:"sha256",value:$hash}}' > headless.json
curl --fail-with-body -sS "$BASE/v1/signatures" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $HEADLESS_REQUEST_KEY" --data-binary @headless.json > signature.json
SIGNATURE=$(jq -er '.id' signature.json)
curl --fail-with-body -sS "$BASE/v1/signatures/$SIGNATURE/simulate" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -d '{"action":"sign"}'
curl --fail-with-body -sS "$BASE/v1/signatures/$SIGNATURE" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY"

Headless signatures

POST /v1/signatures signs one document for one signer with Smart-ID or Mobile-ID, with no hosted page, no invitation and no email. Your application shows the verification code and the signer confirms on their phone. The confirmation sequence depends on the known certificate and configured certificate service. When an identity step comes first, the document-signing step follows with a new code: step moves from authentication to signing and a signature.confirmation_required webhook carries the new code.

Name a profile: cades-detached signs your SHA-256 hash and returns a detached .p7s at CAdES-BASELINE-LT, with the certificate chains and revocation data embedded; pades signs a PDF, such as the PDF/A-2 that ESPBI renders, and returns it signed at PAdES-BASELINE-LT, added in an incremental update; cades-enveloping signs a PDF and returns it inside the signature, as a .pdf.p7m at CAdES-BASELINE-LT (v1.20.0). Since v1.21.0 a whole file goes in document.file: xades-enveloped returns your XML with the signature inside, at XAdES-BASELINE-LT, as e-invoices and XML filings carry it; cades-enveloping-xml returns the XML inside the signature, as an .xml.p7m; asice and edoc put any file in an ASiC-E container at XAdES-BASELINE-LT, named .asice or the Latvian .edoc; jades signs a JSON payload into a JAdES-BASELINE-LT signature (JWS JSON serialization, payload attached). A visible stamp on a pades signature is your choice, as in Tvarka Sign: the signer's name from the signing certificate and the signing time, with the workspace logo where it has one. Send "visibleSignature": true for the default corner, or an object with exact coordinates or an existing empty signature field, in the same shape as for a hosted signer. Without it the signature stays invisible. The stamp speaks the language of your company's country; a company outside Lithuania gets the Tvarka.eu stamp. Send renderHash, the digest of what you showed the signer; it is kept as evidence with the display text, the input digest, the codes and the signing certificate. Every production key signs headless at once. One signature is billed on success; declined, expired, failed and cancelled ones are free. For many documents at once, sign in bulk with the ID card through the ATK API.

Smart-ID by QR code or app link: send "interaction": {"type": "qr"} or {"type": "app_link"} (Smart-ID only). No personal code is needed; an optional Lithuanian signer.personalCode accepts only that person. Show nextAction.qrLink as a QR code and fetch a fresh one every second. app_link needs a registered returnUrl and a returnState; the Smart-ID app brings the signer back to it with state and signatureId. Check that state belongs to the browser that started; the result itself comes only from polling or the webhook.

A start that may have reached the signer's phone without an answer is never sent again: the signature fails as initiation_unknown and is not billed. Ask the signer to dismiss any prompt and retry after two minutes. A 503 with Retry-After means nothing started: retry with the same Idempotency-Key.

Methods and formats

This orchestration API offers LT ATK card signing over NFC in the Tvarka Sign mobile app, plus Smart-ID and Mobile-ID. The separate ATK API is the full low-level LT ATK surface for NFC, USB/readers and raw signatures. Across Tvarka APIs, PAdES, XAdES, CAdES, JAdES and ASiC cover all Regulation (EU) 2026/248 Annex I families.

Signature validation

Validate electronic signatures and retrieve advisory validation results for integration into your document workflows.

Simple e-signature: 0.13 EUR per completed document, excluding VAT, however many signers. An SMS code costs EUR 0.01, excluding VAT.

Related pages

Questions: info@tvarka.pro