Signatures

Start a headless signature

Opens the first confirmation on the signer's phone at once and answers 202 with its verification code. Show the code; poll GET /v1/signatures/{signatureId} or wait for the webhook.

Refusals at create time are never billed: 403 headless-not-enabled (production workspace without the entitlement), 402 payment-required with recoveryUrl when the workspace cannot pay for one signature, 409 signer-busy when the signer already has an active request elsewhere (not queued; retry once it ends), 400 validation-failed listing every rejected field with a JSON Pointer, 422 interaction-unavailable when a QR code or app link is asked for and not switched on, and 422 signer-unreachable when the provider refused because of the person or the request, for example when no account exists for this method. The same request would be refused again. A 503 that carries Retry-After means provably nothing started: retry with the same Idempotency-Key. A start that may have reached the phone answers 202 with status: failed and failureReason: initiation_unknown, never a second start.

post/v1/signatures

Request

  • Base URL: https://sign-api.tvarka.pro
  • URL: https://sign-api.tvarka.pro/v1/signatures
  • 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)

Headers

Idempotency-Keystring

Optional tenant-and-operation-scoped create key (1-128 visible ASCII characters). Identical input replays the original response; changed input or an unresolved execution returns 409. After 90 days the response expires but the key remains reserved. Do not change keys to retry a request with an uncertain outcome.

Request body

method'smart_id' | 'mobile_id' required
returnUrlstring uri

app_link only, and required there: an exact HTTPS URL registered for this API client. Requires returnState.

returnStatestring

Random per-browser-session value, returned as state.

externalIdstring
webhookUrlstring uri

Public HTTPS URL.

Response

The first confirmation is on the signer's phone.

idstring uuid required
status'pending' | 'signed' | 'declined' | 'expired' | 'failed' | 'cancelled' required
method'smart_id' | 'mobile_id' required
interaction'notification' | 'qr' | 'app_link'
step'authentication' | 'signing' required

The confirmation in flight. Tvarka decides which run.

verificationCodestring nullable

Show this to the signer while pending.

expiresAtstring date-time
externalIdstring nullable
failureReason'identity_mismatch' | 'certificate_not_qualified' | 'certificate_rotated' | 'provider_error' | 'timestamp_unavailable' | 'initiation_unknown'

identity_mismatch - the certificate belongs to another person. certificate_not_qualified - the certificate cannot sign documents. certificate_rotated - the signer's certificate changed since Tvarka last saw it; the new one is kept, so a retry needs one confirmation. provider_error - the signing service failed. timestamp_unavailable - no qualified timestamp could be obtained. initiation_unknown - the start may have reached the signer's phone but no answer came back; it is never repeated. Ask the signer to dismiss any prompt and retry after two minutes. None of these is billed.

sandboxboolean
completionMode'signed' | 'sandbox_simulation'
createdAtstring date-time required
completedAtstring date-time nullable

Changes

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