Signings

Add a signer to a live signing

On a sequential signing the newcomer joins the END of the queue: they come back waiting, their link stays dead until their turn, and no delivery goes out before it. Only a parallel signing hands back a live ceremony URL immediately.

post/v1/signings/{signingId}/signers

Request

  • Base URL: https://sign-api.tvarka.pro
  • URL: https://sign-api.tvarka.pro/v1/signings/{signingId}/signers
  • 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)

Path parameters

signingIdstring uuid required

Request body

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.

emailstring email required
namestring
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.

personalCodestring

Optional Lithuanian identity lock. Tvarka stores a keyed hash and encrypted value, never returns the code, and refuses a different authenticated signer.

methodsSigningMethod[]

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.

Response

The signer and their ceremony.

signerIdstring 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.

emailstring email nullable
namestring 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.

ceremonyUrlstring uri

Present only while this signer can still sign. A finished or retracted invitation has no live URL.

signedAtstring date-time nullable
declinedAtstring date-time nullable
declineReasonstring
methodsAllowedSigningMethod[]
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.

identityLockedboolean
signingPurpose'signature' | 'confirmation' | 'visa' | 'registration' | 'null' nullable

Accepted immutable purpose; null for a viewer.

identityMatchedboolean nullable

True only after a locked signer completes the real ceremony.

simulatedAtstring 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.

emailAcceptedAtstring date-time nullable

Changes

No recorded changes to this operation across all 1 revision of this API.