Set PDI Discard Date
This API allows callers to customize the retention period of a conserved document by setting a specific discard date for a given PDI (Pacchetto di Input — Input Package).
Why This API Exists
Once a document has been fully conserved in substitutive storage, it is subject to a default retention period of 10 years from the date of conservation after which it becomes eligible for discarding (scarto). This API exists to give callers precise control over when a specific document becomes eligible for discarding.
How Retention Works
The discard date defines the earliest date after which the PDI is considered eligible for removal. Until that date passes, the document is retained and protected in substitutive storage.
Key rules:
- The default discard date is 10 years from the date of conservation.
- The minimum discard date you can set is now + 1 day this is the shortest possible retention period and allows a document to be discarded as soon as possible.
- The maximum discard date you can set is now + 30 years for cases requiring extremely long-term storage.
- When the discard date of a PDI is updated, the related PdA (Pacchetto di Archiviazione) and PdV (Pacchetto di Versamento) are automatically aligned to the new date.
Important: This API is designed for individual updates. If you need to set discard dates for a large number of documents at once, use the dedicated bulk endpoint set-discard-date-bypass-related-update instead using this API for mass operations would be inefficient and is not recommended.
Use Cases
Use this API when you need to:
- Shorten the retention period — request early discarding for a document that no longer needs to be kept for the full default period.
- Extend the retention period — keep a document beyond the default 10-year window for compliance or archival reasons.
- Override a previously set discard date — replace an earlier custom date with a new one.
- Align retention to a specific business deadline — tie the document's lifecycle to a known contractual or regulatory expiration date.
How to Use the API
Endpoint
POST /api/v1/archive/discard/pdi/set-discard-date
Authentication
Authentication is required. Refer to the Authentication page for how to obtain and use a valid JWT token.
Allowed security roles: User, M2M, Backoffice
Request
Headers
All Standard Headers are required, with the same set as used by the document status API
POST /api/v1/archive/discard/pdi/set-discard-date
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
X-App-Name: <your_app_name>
X-App-Version: <your_app_version>
X-Request-ID: <unique_request_guid>
X-Item-ID: <item_id>
X-Manager-ID: <manager_id>
X-User-ID: <user_id>
Body
The request body must have the following format:
{
"identifier": "132465798456",
"date": "2023-12-31T23:59:59Z",
"massiveRequestId": "1111e2c2-eb39-445f-9e9c-751ab732cf70"
}
identifier(string, required) — The PDI ID of the document whose discard date you want to set. This is the same unique identifier assigned at upload time.date(string, ISO 8601, required) — The new discard date to apply. Must be between now + 1 day (minimum) and now + 30 years (maximum).massiveRequestId(string, UUID, optional) — A correlation identifier for grouping related requests. Useful for tracing a set of related operations performed together.
Responses
The operation is successful if and only if the HTTP response code is 200. Any other response code indicates an error state.
200 OK — Discard date successfully set
{
"identifier": "string",
"date": "2026-02-24T12:51:26.174Z",
"details": "string"
}
identifier— The PDI ID for which the discard date was updated.date— The new discard date that has been applied, in ISO 8601 format.details— A human-readable message providing additional context about the operation result.
Note: When this call succeeds, the PdA and PdV linked to this PDI are automatically updated with the same discard date. No additional calls are needed for those packages.
400 Bad Request
One or more parameters provided in the request are incorrect, or required parameters are missing.
{
"timestamp": "2026-02-24T12:51:26.174Z",
"status": "CONTINUE",
"code": "string",
"message": "string"
}
401 Unauthorized
The provided credentials are not correct.
{
"timestamp": "2026-02-24T12:51:26.175Z",
"status": "CONTINUE",
"code": "string",
"message": "string"
}
403 Forbidden
The authenticated caller does not have the required permissions to perform this operation.
{
"timestamp": "2026-02-24T12:51:26.176Z",
"status": "CONTINUE",
"code": "string",
"message": "string"
}
API Reference
Use the links below to open the interactive OpenAPI (Swagger) documentation for this endpoint in each environment.