---
title: "Send a template to a list, one signing per row"
method: POST
path: "/v1/templates/{templateId}/bulk-sends"
tags: ["Templates"]
---

# Send a template to a list, one signing per row

`POST /v1/templates/{templateId}/bulk-sends`

## Request

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

Every row is checked first, exactly as a single send from the
template would be; one bad row refuses the list and nothing is
created. Then the rows are sent in the background (v1.14.0). A row
may not carry `personalCode` or an `access_code` authentication:
those signings are sent one by one. A simple e-signature list must
fit today's invitation allowance in full (429 `invitation-limit`).

## Path parameters

- `templateId` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- CreateBulkSendRequest
  - `title` string: Every signing's title, unless a row sets its own. Defaults to the template's title.
  - `rows` object[], required
    - `templateRoles` TemplateRolePrefill[]
      - `roleName` string, required: A role name of the template, case ignored.
      - `email` string, email
      - `name` string
      - `language` 'lt' | 'en' | 'de' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi'
      - `personalCode` string: Qualified templates only. Never stored on the template, never returned.
      - `methods` SigningMethod[]: Qualified templates only.
      - `authentication` ESignAuthentication: `level: esign` only, refused on a qualified signing. One way to protect this signer's link: `email_link` (default), `access_code` with `code` (4 to 64 characters you give the signer yourself; Tvarka keeps only a hash), or `sms` with `phoneNumber` (E.164; `422 authentication-unavailable` when SMS codes are not switched on, and never a quiet fall back to the email link).
        - `type` 'email_link' | 'access_code' | 'sms', required
        - `code` string
        - `phoneNumber` string
    - `externalId` string
    - `title` string
  - `delivery` 'link' | 'email'
  - `webhookUrl` string, uri
  - `expiresInDays` integer
  - `softDeadlineInDays` integer

## Response `202`

The list is accepted and queued.

- BulkSend
  - `bulkSendId` string, uuid
  - `templateId` string, uuid, nullable
  - `title` string
  - `status` 'queued' | 'running' | 'finished'
  - `rowsTotal` integer
  - `rowsSent` integer
  - `rowsFailed` integer
  - `createdAt` string, date-time
  - `startedAt` string, date-time, nullable
  - `finishedAt` string, date-time, nullable
  - `rows` object[]: One entry per row sent so far, in list order. Names and emails are not kept.
    - `row` integer
    - `status` 'sent' | 'failed'
    - `signingId` string, uuid
    - `error` string: The problem type slug the row was refused with, such as `payment-required`.

## 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.
- `404`: An RFC 9457 problem document.
- `409`: 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)