Deleting packages

NSEV never deletes packages on its own. Once a package reaches a final state it is stored indefinitely until you remove it explicitly. This page covers how to delete a single package, how to delete many at once, and how deleting differs from revoking a package.

Prerequisites

A valid access token or Basic Auth credentials - see Platform Access
Your tenant’s base URL set as BASE_URL
The Id of each package you want to delete

All examples use Bearer authentication. Replace the token and variable values with your own.

When a package can be deleted

A package can only be deleted when its status is draft or one of the final states finished, archived, rejected, or revoked. Deleting a package in any other state - for example a pending package that is still out for signature - returns 409 Conflict with the error code Package.InvalidStatus. If you need to remove a package that is still pending, revoke it first (see Deleting versus revoking below), then delete the revoked package.

Delete a single package

Send a DELETE to /packages/{packageId}. On success the call returns 204 No Content.

curl -X DELETE "$BASE_URL/packages/$PACKAGE_ID" \
  -H "Authorization: Bearer {access_token}" \
  -H "User-Agent: MyApp/1.0"

Status	Meaning
`204 No Content`	The package was deleted.
`404 Not Found`	No package with that `Id` exists (`Package.NotFound`).
`409 Conflict`	The package’s status does not allow deletion (`Package.InvalidStatus`).

Delete packages in bulk

To remove many packages at once, POST their IDs to /packages/delete/bulk. The same status rule applies to every package in the list - only draft, finished, archived, rejected, or revoked packages can be deleted.

curl -X POST "$BASE_URL/packages/delete/bulk" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "PackageIds": [
      "b459d74c-1f90-4d63-9f4a-6de9cead8c5e",
      "1fdbad81-75e5-4cc8-b113-39255fa119d7"
    ]
  }'

Bulk actions are processed asynchronously, so the call does not report per-package success immediately. Instead it returns a bulk action session identifier - a GUID - that you use to follow progress.

"b459d74c-1f90-4d63-9f4a-6de9cead8c5e"

Polling the bulk action session

Pass the returned identifier to GET /packages/bulkactionsession/{bulkActionSessionId} to check whether processing has finished and how many packages succeeded or failed. Add ?includeDetails=true to get a per-package breakdown.

curl "$BASE_URL/packages/bulkactionsession/$SESSION_ID?includeDetails=true" \
  -H "Authorization: Bearer {access_token}" \
  -H "User-Agent: MyApp/1.0"

{
  "SessionId": "b459d74c-1f90-4d63-9f4a-6de9cead8c5e",
  "Action": "DeletePackage",
  "Status": "Finished",
  "Total": 2,
  "Succeeded": 1,
  "Failed": 1,
  "FinishedTime": "2025-02-27T09:09:46Z",
  "Details": {
    "Succeeded": [
      { "PackageId": "1fdbad81-75e5-4cc8-b113-39255fa119d7", "ExecutedTime": "2025-02-27T09:09:40Z" }
    ],
    "Failed": [
      {
        "PackageId": "9b2e6f3a-1c44-4e2b-8a77-2d6f0a1b3c4d",
        "ExecutedTime": "2025-02-27T09:09:42Z",
        "ErrorCode": "Package.InvalidStatus",
        "ErrorMessage": "The package is not in a final state."
      }
    ]
  }
}

Status moves from Pending through Finishing to Finished; FinishedTime is only populated once the session reaches Finished. Poll until then. The Action field identifies the kind of bulk action the session ran - for a bulk delete it is DeletePackage.

Because each package in a bulk delete is processed independently, a session can finish with a mix of successes and failures - for example when some packages are in a deletable state and others are not. Always check Failed and the per-package Details rather than assuming the whole batch succeeded.

Audit trails

The audit trail - the human-readable and machine-readable record of a package’s events - is retrieved while the package still exists, through GET /packages/{packageId}/audittrail. Once a package is deleted it can still be fetched but will not contain stakeholders information, so if you need a full copy of the audit trail for your records, retrieve it before deleting the package. For a final package you can also request the audit-trail PDFs of many packages at once with POST /packages/audittrails/download/bulk, which returns a bulk action session you poll and then download as a .zip.

Deleting versus revoking

Deleting and revoking are different operations with different effects:

Revoking changes a package’s status to revoked. The package still exists; it has simply been withdrawn so stakeholders can no longer act on it. Revoking is a pending → revoked status transition, done with PUT /packages/{packageId}/status (or, for many packages, POST /packages/status/bulk).
Deleting removes the package record from the database entirely. It is only allowed once the package is in draft or a final state - including revoked.

So to get rid of a package that is still out for signature, you revoke it first and then delete it. Revoking is the way to stop an in-flight package; deleting is the way to remove a finished or withdrawn one.

When revoking in bulk you can set SuppressNotifications to true so stakeholders are not emailed about the revocation. See Callbacks and redirects for how NSEV’s notifications work.

Next steps

Create and activate packages in Send a document for signing
Understand package statuses and the object model in The package model
Review Best Practices for error handling, pagination, and security

Concepts

Tutorials

Guides

Prerequisites

When a package can be deleted

Delete a single package

Delete packages in bulk

Polling the bulk action session

Audit trails

Deleting versus revoking

Next steps

​Prerequisites

​When a package can be deleted

​Delete a single package

​Delete packages in bulk

​Polling the bulk action session

​Audit trails

​Deleting versus revoking

​Next steps

Prerequisites

When a package can be deleted

Delete a single package

Delete packages in bulk

Polling the bulk action session

Audit trails

Deleting versus revoking

Next steps