---
title: "PDF stamps - Rest PKI Core"
description: "Stamp a PDF with POST api/pdf/stamp: Rest PKI Core adds a PAdES document timestamp from one of its timestamp tiers, optionally with a visible appearance. How it differs from PDF marks."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# PDF stamps - Rest PKI Core

A **stamp** is a PAdES document timestamp that [Rest PKI Core](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core) adds to a PDF: a timestamp from one of the instance's
[timestamp tiers](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/requesting-timestamps), embedded in the PDF as a signature field, which proves that the document existed in that
exact form at that time. It doesn't involve a signer's certificate, so no user takes part. Optionally, the stamp has a visible appearance, with text
and an image, on one page of the PDF.

> **Tip**
>
> From this point on we'll describe calls to Rest PKI Core. Make sure you've read the [Get Started](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started) article to be able to keep up. The
> application's API key needs a role that allows stamping PDFs, such as **Worker** (see [Choosing roles](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#roles)).

## Stamping a PDF

On .NET, call `IRestPkiService.StampPdfAsync()` with the PDF, as a [file reference](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/file-referencing), and the options:

```cs
var result = await restPkiService.StampPdfAsync(FileReference.FromFile(@"C:\AppData\Documents\document.pdf"), new StampPdfOptions() {
	TimestampTier = "PkiBrazil",
});

// result.File is a reference to the stamped PDF
```

Pass the options even if you set none of them: `StampPdfAsync()` doesn't accept `null`.

If calling the API directly, do:

```text
POST {endpoint}/api/pdf/stamp
{
	"file": {
		"content": "JVBERi0xLjcK...",
		"name": "document.pdf"
	},
	"timestampTier": "PkiBrazil"
}
```

The request has these fields (in .NET, the properties of `StampPdfOptions`, with the same names):

| Field | Description |
| --- | --- |
| `file` | The PDF. Required |
| `timestampTier` | The ID or name of the timestamp tier, such as `PkiBrazil`. If omitted, Rest PKI Core uses the instance's default tier: on the SaaS instance, always name the tier (see [Requesting timestamps](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/requesting-timestamps)) |
| `customSignatureFieldName` | The name of the signature field of the stamp in the PDF. Up to 100 characters, without dots |
| `reason` | The reason recorded in the stamp. Up to 1024 characters |
| `visualRepresentation` | The visible appearance of the stamp: see [below](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp#visual-representation). Without it, the stamp is not visible on the pages |
| `forceBlobResult` | Return the stamped PDF as a temporary link even when it is small (see [The result](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp#result)) |

The call fails with `TimestampTierNotFound` when the tier doesn't exist, with `TimestampTierDisabled` when it is disabled, and with
`TimestampTierRestricted` when your subscription can't use it. A page number beyond the last page fails with `InvalidPage`.

On Node.js, the [restpki-core-client](https://www.npmjs.com/package/restpki-core-client) library calls this route with `stampPdf()`, and on Python,
[restpki-ng-python-client](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#python) with `PdfApi.api_pdf_stamp_post()`. The Java and PHP libraries have no working method for it:
call the route directly, as described in [Calling the API directly](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#rest).

Each stamp is counted as a **PDF stamp** transaction. The call fails when the subscription has reached its limit of PDF stamp or of timestamp transactions.

## The visible appearance

`visualRepresentation` takes the same model as the visual representation of a PAdES signature, with `text`, `image` and `position`. For instance,
the stamp drawn by the dashboard's demo, at the bottom of the first page:

```json
"visualRepresentation": {
	"text": {
		"text": "Lacuna Software",
		"fontSize": 13.0,
		"includeSigningTime": true,
		"horizontalAlign": "Left",
		"container": { "left": 0.2, "top": 0.2, "right": 0.2, "bottom": 0.2 }
	},
	"image": {
		"resource": { "url": "https://cdn.lacunasoftware.com/img/pdf-stamp.png", "mimeType": "image/png" },
		"horizontalAlign": "Right",
		"verticalAlign": "Center"
	},
	"position": {
		"pageNumber": 1,
		"measurementUnits": "Centimeters",
		"auto": {
			"container": { "left": 1.0, "right": 1.0, "bottom": 1.0, "height": 4.94 },
			"signatureRectangleSize": { "width": 8.0, "height": 4.94 },
			"rowSpacing": 0.3,
			"horizontalDirection": "LeftToRight",
			"verticalDirection": "BottomUp"
		}
	}
}
```

The text is drawn as given: tags such as `{{name}}`, which a signature replaces with data of the signer's certificate, are not replaced on a stamp,
since there is no signer.

## The result

The result is the stamped PDF, as a file reference: in `content`, in Base64, when it has up to 5 MB, or else as a `url` from which you can download it
for a limited time. With `forceBlobResult = true`, it always comes as a `url`. In .NET, `result.File` is a `FileReference`.

Inspecting the stamped PDF with [signature inspection](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection) lists the stamp as a signer with `isDocumentTimestamp = true`.

### Signed PDFs

You can stamp a PDF that is already signed. Rest PKI Core doesn't validate the signatures already in it when stamping, and the stamp is added the way
a new signature is, as the PKI SDK does to [add LTV](https://docs.lacunasoftware.com/en-us/articles/pki-sdk/signatures/pades/ltv) to a signed PDF.

## Trying it on the dashboard

On instances that issue timestamps, the dashboard has a demo: on the left menu, click **Demos**, then **PDF Stamp**. Choose a **Timestamp tier**,
upload a PDF and click **Stamp**: the dashboard opens the stamped PDF, with the appearance shown [above](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp#visual-representation).

## Stamps and PDF marks

A stamp is not the newer form of the PDF marks of [Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki) (`PdfMarker`, `POST Api/Pdf/AddMarks`), which draw text,
images and QR codes on the pages, for instance to make the printer-friendly version of a signed document. Rest PKI Core still serves the marks route
with the Rest PKI models (see [Moving from Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/migrating-from-rest-pki#served-apis)), and the two do different things:

| | PDF marks (`Api/Pdf/AddMarks`) | Stamp (`api/pdf/stamp`) |
| --- | --- | --- |
| **What it adds** | Drawings on the pages, without cryptography | A document timestamp, with an optional appearance |
| **What it can draw** | Several elements per mark, with styled text, images, QR codes, borders, backgrounds and rotation | One appearance, with a text and an image |
| **Where** | Every page, one page (counted from the start or the end) or a new page | One page |
| **On a signed PDF** | Invalidates the signatures, unless `abortIfSigned` makes the call fail with `CannotApplyPdfMarks` instead | Stamps it (see [Signed PDFs](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp#signed-pdfs)) |
| **Timestamp** | None | Issued by a timestamp tier |
| **On Rest PKI** | `PdfMarker` | No equivalent |

## See also

* [Requesting timestamps](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/requesting-timestamps)
* [Signature inspection](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection)
* [Referencing files](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/file-referencing)