---
title: "Document lifecycle"
description: "Operations in the Signer document lifecycle through the API: cancel, refuse, pause and resume, submit a new version, delete and restore a document."
canonical: "https://docs.lacunasoftware.com/en-us/articles/signer/integration/lifecycle"
locale: "en"
product: "Signer"
last_updated: "2026-10-22"
---

# Document lifecycle

Beyond creating and tracking, you can perform operations throughout the document's life: cancel, refuse, pause and resume, submit a new version, delete and restore.

## Cancel document

To cancel a document, send the document ID in a `POST` request with the `reason` field:

```javascript
POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/cancellation

{
    "reason": "This is a document cancellation"
}
```

**Examples on GitHub:** [C#](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/CancelDocumentScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/CancelDocumentScenario.java) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/CancelDocumentScenario.php) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/cancelDocumentScenario.ts)

## Refuse a document

To refuse a document, send the document ID in a `POST` request with the `reason` field:

```javascript
POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/refusal

{
    "reason": "This is a document refusal"
}
```

**Examples on GitHub:** [C#](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/RefuseDocumentScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/RefuseDocumentScenario.java) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/RefuseDocumentScenario.php) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/refuseDocumentScenario.ts)

## Pause and resume a document

Available from version 3.0.0. Pausing holds the flow of an in-progress document. While the document is paused, nobody can sign, approve or refuse it. The signatures and approvals already made stay on the document.

To pause, send a `POST` with the reason in the `reason` field. The reason is optional and accepts up to 500 characters:

```javascript
POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/pause

{
    "reason": "Waiting for legal review"
}
```

To resume, send a `POST` with no body. The document goes back to the `Pending` status and the flow continues from where it stopped:

```javascript
POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/resume
```

### Who can pause

The same people can pause and resume:

* The document's creator, including the application that created the document through the API.
* The organization's administrators and managers.
* The administrators and managers of the document's folder. A folder operator can pause only the documents they created.
* System administrators.

Without this permission, the API responds `403`.

### What happens while the document is paused

* The document has the `Paused` status. Treat it as an in-progress document, like `Pending`. See [Document status](https://docs.lacunasoftware.com/en-us/articles/signer/integration/tracking#document-status).
* Participants whose action was already released receive an e-mail when the document is paused, with the reason, and another one when it is resumed.
* A participant who opens the link sees the document but cannot sign, approve or refuse it.
* The Signer sends no reminders, and the document does not expire. If the expiration date has already passed when you resume the document, it expires right away.
* The Signer sends the [`DocumentPaused`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentpaused) and [`DocumentResumed`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentresumed) webhooks.
* You can cancel the document. The other operations fail with a `422` error: edit the flow, edit the information, submit a new version, restart the flow, remove a signature, submit files, edit the notified e-mails, send reminders and generate a share link. The error codes start with `Cannot` and end with `PausedDocument`, for example `CannotSignPausedDocument` and `CannotEditPausedDocumentFlow`.

### Pause errors

| Code | When |
| --- | --- |
| `DocumentPauseDisabled` | The instance turned pausing off with the `General:EnableDocumentPause` setting (see [Signer settings](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/settings)). |
| `DocumentAlreadyPaused` | The document is already paused. |
| `CannotPauseConcludedDocument`, `CannotPauseFlowConcludedDocument` | The document is already concluded, or all flow actions are already done. |
| `CannotPauseCanceledDocument`, `CannotPauseRefusedDocument`, `CannotPauseExpiredDocument` | The document was canceled, refused or expired. |
| `DocumentNotPaused` | You asked to resume a document that is not paused. |

## Submit a new document version

It is possible to upload a new version of an already created document. To do so, send the document ID in a `POST` request along with the new version's file.

> **Caution**
>
> When submitting a new version, the **signing flow is reset**.

**Examples on GitHub:** [C#](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/AddNewDocumentVersionScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/AddNewDocumentVersionScenario.java) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/AddNewDocumentVersionScenario.php) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/addNewDocumentVersionScenario.ts)

## Delete document

To delete a document, you need its ID and make a `DELETE` request:

```javascript
DELETE /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11
```

**Examples on GitHub:** [C#](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/DeleteDocumentScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/DeleteDocumentScenario.java) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/DeleteDocumentScenario.php) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/deleteDocumentScenario.ts)

## Restore a deleted document

The web interface does not restore deleted documents, but the API does. Only an API key with the system administrator role can call the APIs in this section. To get such a key, create the application in the `Sys Admin` organization, as shown in [Administration APIs](https://docs.lacunasoftware.com/en-us/articles/signer/on-premises/administration#creating-an-administration-api-key).

Send the document IDs in the `ids` field:

```javascript
POST /api/documents/restore

{
    "ids": [ "b12cb1b2-5d6e-40b2-a050-097d068c4c11" ]
}
```

The response is the ID of a background job. The job restores each document with the status it had before it was deleted, and ignores documents that are not deleted.

To bring a canceled or expired document back into the flow, use `POST /api/documents/restore-status`. The body has the `ids` and `removeExpirationDateForExpiredDocs` fields. The Signer recalculates each document's status, with one exception for a past expiration date:

* If `removeExpirationDateForExpiredDocs` is `false`, a document whose expiration date has passed stays `Expired`.
* If `removeExpirationDateForExpiredDocs` is `true`, the Signer removes the expiration date and recalculates the status.

The job ignores documents that are neither canceled nor expired. The response is also the job ID.

**Demos and samples**

- Cancel a document: [.NET](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/CancelDocumentScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/CancelDocumentScenario.java) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/cancelDocumentScenario.ts) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/CancelDocumentScenario.php)
- Refuse a document as the organization: [.NET](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/RefuseDocumentScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/RefuseDocumentScenario.java) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/refuseDocumentScenario.ts) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/RefuseDocumentScenario.php)
- Delete a document: [.NET](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/DeleteDocumentScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/DeleteDocumentScenario.java) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/deleteDocumentScenario.ts) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/DeleteDocumentScenario.php)
- Upload a new version of a document: [.NET](https://github.com/LacunaSoftware/SignerSamples/blob/master/dotnet/console/Console/Scenarios/AddNewDocumentVersionScenario.cs) · [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/AddNewDocumentVersionScenario.java) · [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/addNewDocumentVersionScenario.ts) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/AddNewDocumentVersionScenario.php)