Pular para o conteúdo principal

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:

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

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

Examples on GitHub: C# · Java · PHP · Node.js

Refuse a document​

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

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

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

Examples on GitHub: C# · Java · PHP · Node.js

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:

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:

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.
  • 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 and 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​

CodeWhen
DocumentPauseDisabledThe instance turned pausing off with the General:EnableDocumentPause setting (see Signer settings).
DocumentAlreadyPausedThe document is already paused.
CannotPauseConcludedDocument, CannotPauseFlowConcludedDocumentThe document is already concluded, or all flow actions are already done.
CannotPauseCanceledDocument, CannotPauseRefusedDocument, CannotPauseExpiredDocumentThe document was canceled, refused or expired.
DocumentNotPausedYou 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# · Java · PHP · Node.js

Delete document​

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

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

Examples on GitHub: C# · Java · PHP · Node.js

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.

Send the document IDs in the ids field:

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.

View as Markdown