---
title: "Cancel a pending signature"
method: POST
path: "/v1/signatures/{signatureId}/cancel"
tags: ["Signatures"]
---

# Cancel a pending signature

`POST /v1/signatures/{signatureId}/cancel`

## Request

- Base URL: `https://sign-api.tvarka.pro`
- URL: `https://sign-api.tvarka.pro/v1/signatures/{signatureId}/cancel`
- 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`)

A confirmation already on the phone cannot be withdrawn there; if
the signer still confirms it, the result is discarded and not
billed.

## Path parameters

- `signatureId` string, uuid, required

## Response `200`

The signature is cancelled.

- Signature
  - `id` string, uuid, required
  - `status` 'pending' | 'signed' | 'declined' | 'expired' | 'failed' | 'cancelled', required
  - `method` 'smart_id' | 'mobile_id', required
  - `interaction` 'notification' | 'qr' | 'app_link'
  - `nextAction` NextAction: What to show the signer now (v1.11.0). `revision` grows with every step and once more at the end; ignore a webhook whose revision is older than the one you hold, and poll when unsure.
    - `type` 'compare_code' | 'confirm_certificate' | 'scan_qr' | 'open_app' | 'wait' | 'none', required
    - `revision` integer, required
    - `verificationCode` string: With `compare_code`.
    - `qrLink` string, uri: With `scan_qr`. Show as a QR code; it changes every second.
    - `refreshAfterSeconds` integer: With `scan_qr`: fetch a new link after this long.
    - `appLink` string, uri: With `open_app`: open on the signer's phone.
    - `expiresAt` string, date-time
  - `step` 'authentication' | 'signing', required: The confirmation in flight. Tvarka decides which run.
  - `verificationCode` string, nullable: Show this to the signer while `pending`.
  - `expiresAt` string, date-time
  - `externalId` string, nullable
  - `document` object
    - `name` string
    - `profile` string
    - `inputSha256` string, nullable: Hex digest the signature covers.
  - `visibleSignature` union: The stamp chosen at create (v1.13.0): `false` for none, `true` for the default corner, the accepted placement, or null for a hash.
    - boolean
    - 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
  - `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.
  - `sandbox` boolean
  - `completionMode` 'signed' | 'sandbox_simulation'
  - `createdAt` string, date-time, required
  - `completedAt` string, date-time, nullable
  - `result` object: Present once `signed`.
    - `profile` string
    - `level` string, nullable: For example CAdES-BASELINE-LT.
    - `sha256` string
    - `bytes` integer
    - `signingTime` string, date-time, nullable
    - `timestampTime` string, date-time, nullable
    - `certificate` object, nullable
      - `subjectCommonName` string
      - `issuer` string
      - `serialNumber` string: Certificate serial, hex.
      - `notAfter` string, date-time
      - `qualified` boolean: The certificate states it is qualified and on a qualified signature creation device. A statement in the certificate, not a trusted-list verdict.
    - `validation` object, nullable: Advisory. `notApplicable` for `cades-detached`: a detached signature over a hash is validated beside the document, which Tvarka never receives.
    - `available` boolean: False once the artifact was erased.

## Other responses

- `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`: The signature had already ended.
- `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)