---
title: "Prepare an envelope for signature"
method: POST
path: "/api/v1/rest/firme/envelopes"
tags: ["Signatures"]
---

# Prepare an envelope for signature

`POST /api/v1/rest/firme/envelopes`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/firme/envelopes`
- Auth: HTTP bearer

Creates a DRAFT envelope with its recipients. Nothing is sent until firme_send_envelope. The PDF is an Archivio document: pass its `document_id` (find it with documents_search) and its current version is signed, and the signed copy becomes its next version. A brand-new file goes into the Archivio first with documents_upload. `source_sha256` names a PDF staged through the REST upload instead; with `document_id` too it must be that document’s current version. Only a PDF can be signed. Every envelope is a firma elettronica closed with a qualified electronic seal; there is no level to choose.

## Headers

- `X-Tenant-Id` string, uuid

## Request body

- object
  - `title` string, required
  - `document_id` string, uuid: The Archivio document to sign: its current version is the PDF, and the signed copy becomes its next version.
  - `source_sha256` string: A PDF staged through POST /api/v1/firme/source, instead of a document.
  - `source_filename` string: Required with `source_sha256`; defaults to the document’s file name.
  - `message` string: Shown to the recipients.
  - `routing` 'sequential' | 'parallel': `sequential` invites signers one at a time, in order; `parallel` all at once.
  - `archive_on_complete` boolean: `true` files the signed PDF in the Archivio once everybody has signed; `false` keeps it in Firme only.
  - `default_signature_field` boolean: Put a signature box at the foot of the last page for every signer. Without it the first signature is a strip along the left edge of page 1 and later ones are invisible (they are in the file all the same).
  - `mail_account_id` string, uuid: The organisation mailbox the invitations, reminders and signed copy leave from (an id from email_list_accounts). Omit for the module default.
  - `whatsapp_account_id` string, uuid: The WhatsApp number the links, codes and copy are written from (an id from whatsapp_list_accounts). Omit to let the organisation pick.
  - `signers` object[], required: In signing order. Only `signer` produces a signature.
    - `name` string, required
    - `email` string, email
    - `whatsapp` string: Their WhatsApp number, with the international prefix (+39 347 …).
    - `send_via` 'email' | 'whatsapp': Where the signing link goes: `email` or `whatsapp` (needs `whatsapp`).
    - `whatsapp_code` boolean: Ask for a one-time code sent to their WhatsApp before they sign.
    - `role` 'signer' | 'cc': `signer` signs; `cc` receives a read-only link when the envelope is sent and the signed copy when it is complete, and never signs.
    - `send_copy` boolean: Send them the signed PDF once everybody has signed, the way the link went.

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `409`: The record is in a state that does not allow it — under legal hold, already sent, already closed. `error.code` says which.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)