---
title: "PDF validation marks - Rest PKI Core"
description: "How Rest PKI Core adds validation marks to a PDF before its first signature, the marked file (markedFile) and the PDF marking policy (Never, WhenPossible, Always)."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-marking"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-10-20"
---

# PDF validation marks - Rest PKI Core

Before the **first signature** of a PDF, [Rest PKI Core](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core) can produce a copy of it with **validation marks**: visual elements, such as
the link to verify the document, that help whoever reads the PDF check its signature. How the marks look comes from the marking options of the
organization (*subscription*). That copy is the **marked file**, and it is the one that gets signed when the PDF is marked.

The marked file appears as `markedFile` in the document summary (`GET api/documents/{id}`) and in the [webhook notifications](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/webhooks). It only
exists when the original file is a PDF and was marked; otherwise it is null. Applications that perform CMS signatures of PDFs can hand the marked file
to users instead of the `.p7s` file: it is a PDF that anyone can open. In detached CMS signatures, the marked file is the data file that corresponds
to the `.p7s`.

A co-signature of a document that was already signed in the system never gets marks. Marking only applies to signatures made through `api/signature` (two-step) and signature sessions; the legacy Rest PKI-compatible APIs never mark the PDF.

## Marking policy

The **PDF marking policy** decides whether the PDF is marked before being signed and what happens when the marks can't be added. Adding marks to a PDF
that already has signatures would invalidate them, and that is where the policies differ:

| Value | In the dashboard | Behavior |
| --- | --- | --- |
| `Never` | Never | No marks are added: the original PDF is signed. |
| `WhenPossible` (default) | When possible | Rest PKI Core tries to add the marks. If the submitted PDF already has signatures (for example, it was signed elsewhere), the marked file is silently discarded and the original PDF is signed. |
| `Always` | Always | The marks are mandatory. If the submitted PDF already has signatures, the [two-step signature](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/two-step-signatures) fails with the `PdfAlreadySigned` code and, in a [signature session](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions), the signer sees a file-already-signed error. |

## Configuration

The policy is set per organization, in the **PDF marking policy** option of the dashboard. The **Use system default** option leaves the organization
without its own policy, so the instance setting `Pdf:MarkingPolicy` applies, whose default is `WhenPossible`. See
[PDF Settings](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/on-premises/settings/pdf). The policy is not chosen per request.

Don't confuse it with the custom marks of a PAdES signature (`PdfSignatureOptions.Marks`) or with the marks of `api/pdf/AddMarks`: those are
different features, described in [PDF stamps](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp#marks).