---
title: "Send a PDF to a tablet"
method: POST
path: "/v1/kiosk-sessions"
tags: ["Kiosks"]
---

# Send a PDF to a tablet

`POST /v1/kiosk-sessions`

## Request

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

Sends one PDF to a kiosk for a drawn e-signature (v1.15.0). The
document takes the signing intake (`content`, `fileToken`, `url`,
`markdown`). No link is mailed; the person signs on the tablet.
`identity: sms` sends a one-time code to `signer.phone` and checks it
on the tablet before signing. A busy kiosk answers 409.

`product: forms` with `formRequestId` sends a Tvarka Formos request
to the kiosk instead (v1.17.0). The person fills the form on the
tablet, with each field in its place on the document page, reviews
it and signs it there by hand. A template with a staff signature
place, such as the doctor's, is signed by the staff member next, on
the same tablet. `title`, `document`, `signer` and `identity` are not
used then. A request already on a kiosk answers with that session.
`assisted: true` starts in assisted mode.

## Headers

- `Idempotency-Key` string

## Request body

- CreateKioskSessionRequest: A PDF to sign (`product: sign`, the default) needs `title` and `document`. A form request (`product: forms`) needs `formRequestId`.
  - `kioskId` string, uuid, required
  - `product` 'sign' | 'forms'
  - `formRequestId` string, uuid: With product forms, the form request to fill and sign on the kiosk.
  - `assisted` boolean: Start in assisted mode.
  - `title` string
  - `document` object: One PDF, through the same intake as a signing's `document`.
    - `name` string
    - `content` string, byte
    - `fileToken` string, uuid
    - `markdown` string
    - `url` string, uri
  - `signer` object
    - `name` string: Left empty
    - `email` string, email: Receives the signed PDF.
    - `phone` string: Required with identity sms.
  - `identity` 'attended' | 'sms'

## Response `201`

The kiosk session, waiting for the tablet.

- KioskSession
  - `kioskSessionId` string, uuid
  - `kioskId` string, uuid
  - `status` 'waiting' | 'in_progress' | 'assisted' | 'ready' | 'signing' | 'completed' | 'cancelled' | 'expired' | 'failed'
  - `assisted` boolean
  - `title` string
  - `signerName` string, nullable
  - `identity` 'attended' | 'sms'
  - `createdAt` string, date-time
  - `completedAt` string, date-time, nullable
  - `revision` integer
  - `product` 'sign' | 'forms' | 'sauga'
  - `formRequestId` string, uuid, nullable: With product forms.
  - `referenceCode` string: The public check code

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