Signings

Create a signing

Stores the document, opens one ceremony per signer, and returns the ceremony URLs (or emails them, with delivery: email). level: esign asks for a simple e-signature (v1.11.0); see the description above.

All signers sign the same document and are unordered: whoever opens their link first signs first, and each subsequent signer signs the output the previous one produced. Two signers never sign at the same moment - the ceremony serializes them.

post/v1/signings

Request

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

OR
OR

Response

The signing was created and every signer has a live ceremony.

signingIdstring uuid
status'pending' | 'completed' | 'declined' | 'cancelled' | 'expired' | 'failed'

pending - at least one signer can still sign. completed - every signer signed. declined - somebody declined and nobody else can still sign. expired - the window closed first. cancelled - you retracted it. failed - the signing could not be prepared.

level'qualified' | 'esign'
processingStage'awaiting_signers' | 'finalizing'

While pending: finalizing once every signer signed and the file is being sealed (a simple e-signature's document timestamp).

titlestring
delivery'link' | 'email'
signingOrder'parallel' | 'sequential'

sequential releases one signer at a time in the order they were posted. The signers who are waiting hold a ceremony link that answers 404 until their turn, so the ordering is enforced rather than merely unsent. A decline stops the workflow at the decliner's turn: the signing settles declined and the signers still waiting are cancelled.

softDeadlineAtstring date-time nullable

The date the signing is wanted by, as opposed to expiresAt, which is the date it dies on. Nothing expires here; it is when the one automatic reminder goes out.

externalIdstring nullable
templateIdstring uuid

Present when the signing was sent from a template (v1.14.0).

createdAtstring date-time
expiresAtstring date-time nullable
completedAtstring date-time nullable
completionMode'qes_ceremony' | 'esign_ceremony' | 'sandbox_simulation' | 'null' nullable

qes_ceremony means human eID signing. esign_ceremony means a completed simple e-signature. sandbox_simulation exercises lifecycle/webhook integration and creates no signature; its artifact is flagged sandbox: true.

erasedAtstring date-time nullable
detailstring

Present when the status needs a sentence of explanation.

Changes

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