---
title: "Add a signer to a live signing"
method: POST
path: "/v1/signings/{signingId}/signers"
tags: ["Signings"]
---

# Add a signer to a live signing

`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`)

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.

## Path parameters

- `signingId` string, uuid, required

## Request body

- SignerRequest
  - `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

## Response `201`

The signer and their ceremony.

- 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

## Other responses

- `400`: An RFC 9457 problem document.
- `401`: An RFC 9457 problem document.
- `402`: An RFC 9457 problem document.
- `403`: An RFC 9457 problem document.
- `404`: An RFC 9457 problem document.
- `409`: An RFC 9457 problem document.
- `413`: An RFC 9457 problem document.
- `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)