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.
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.
/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)./v1/timestamps and MCP seal a file, a hash or a captured web page, also from a chosen place (timestamps)./v1/signings and MCP prepare documents, invite signers, track progress and return signed originals./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.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.
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.
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
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.
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.
These are browser settings, not new bearer-key REST endpoints or MCP tools. Do not add logo, tagline or entitlement fields to signing requests.
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.{"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.qualified and esign) only: containers and viewers cannot use placement.
Field binding cannot be combined with document.flatten: true.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.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.
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.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.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.
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.
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.
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.
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.
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.
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"
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.
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.
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.
Questions: info@tvarka.pro