---
title: "Correct a draft envelope"
method: PATCH
path: "/api/v1/rest/firme/envelopes/{id}"
tags: ["Signatures"]
---

# Correct a draft envelope

`PATCH /api/v1/rest/firme/envelopes/{id}`

## Request

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

Corrects a DRAFT envelope before it is sent: its title, the message the recipients read, the signing order, whether the signed PDF is filed in the Archivio, and its recipients — any of them in one call. Only a draft can be changed; once sent, an envelope can only be voided. `signers` REPLACES THE WHOLE LIST: pass everybody who should stay, in signing order, not only the person being added (read the list with firme_get_envelope first). Every recipient named here signs through an emailed link; what the web app arranged for the old list (signature boxes on the page, a colleague signing in the app, signing in person) does not carry over. Nobody is contacted: sending is firme_send_envelope, which a person approves.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Tenant-Id` string, uuid

## Request body

- object
  - `title` string
  - `message` string, nullable: Shown to the recipients. `null` removes it.
  - `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.
  - `mail_account_id` string, uuid, nullable: 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, nullable: The WhatsApp number the links, codes and copy are written from (an id from whatsapp_list_accounts). Omit to let the organisation pick.
  - `default_signature_field` boolean: With `signers`: a signature box at the foot of the last page for each.
  - `signers` object[]: The COMPLETE new list, in signing order: it replaces the old one. 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.
- `404`: Nothing with that id in this organisation.
- `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)