---
title: "Save a template"
method: POST
path: "/v1/templates"
tags: ["Templates"]
---

# Save a template

`POST /v1/templates`

## Request

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

Saves a copy of one unsigned PDF with its roles (v1.14.0). The
document takes the signing intake (`content`, `fileToken`, `url`,
`markdown`; Office files and images are converted to PDF). A role's
`visibleSignature` is checked against the PDF now. A role with an
`email` has a saved signer, who is invited on every send unless the
send names the role with another person.

## Headers

- `Idempotency-Key` string

## Request body

- CreateTemplateRequest
  - `title` string, required
  - `document` object, required: One PDF, through the same intake as a signing's `document`.
    - `name` string
    - `content` string, byte
    - `fileToken` string, uuid
    - `markdown` string
    - `url` string, uri
  - `level` 'qualified' | 'esign'
  - `signingOrder` 'parallel' | 'sequential'
  - `expiresInDays` integer
  - `roles` object[], required: In signing order. Role names are unique, case ignored.
    - `roleName` string, required
    - `name` string
    - `email` string, email
    - `language` 'lt' | 'en' | 'de' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi'
    - `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

## Response `201`

The saved template.

- Template
  - `templateId` string, uuid
  - `title` string
  - `level` 'qualified' | 'esign'
  - `signingOrder` 'parallel' | 'sequential'
  - `expiresInDays` integer, nullable
  - `document` object
    - `name` string
    - `sha256` string
    - `bytes` integer
  - `roles` TemplateRole[]
    - `roleName` string, required
    - `name` string, nullable
    - `email` string, email, nullable: A saved signer, invited on every send unless the send names this role with another person.
    - `language` string, nullable
    - `visibleSignature` 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
  - `createdAt` string, date-time
  - `lastUsedAt` string, date-time, nullable
  - `useCount` integer

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