---
title: "PAdES visual representation - Rest PKI Core"
description: "Set the visible appearance of a PAdES signature in Rest PKI Core: text with tags, image, manual or automatic positioning on the page, and the positioning presets."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-11-03"
---

# PAdES visual representation - Rest PKI Core

The **visual representation** of a PAdES signature is its visible appearance on the PDF: a text, an image or both, drawn inside a rectangle on one of
the pages. It is optional: without it, the signature is **invisible**, but still valid, and PDF readers list it in their signatures panel.

The visual representation has three parts: the [text](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#text), the [image](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#image) and the [position](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#position) of the rectangle on the page. Only the
position is required.

```json
"visualRepresentation": {
	"text": { ... },
	"image": { ... },
	"position": { ... }
}
```

> **Tip**
>
> From this point on we'll describe calls to [Rest PKI Core](https://docs.lacunasoftware.com/en-us/articles/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.

## Where to set it

The visual representation is part of the PDF signature options, `pdfSignatureOptions`, as the `visualRepresentation` field:

| API | Where |
| --- | --- |
| [Signature sessions](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions): `POST {endpoint}/api/signature-sessions` | `pdfSignatureOptions.visualRepresentation`, which applies to every PDF signed in the session |
| Signature sessions, [predefined documents](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions#predefined-documents) | `documents[].pdfSignatureOptions.visualRepresentation`, for one document |
| [Two-step signatures](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/two-step-signatures): `POST {endpoint}/api/signature` | `pdfSignatureOptions.visualRepresentation` |
| [PDF stamps](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp): `POST {endpoint}/api/pdf/stamp` | `visualRepresentation`, at the top level of the request. It takes the same model described here, but the tags of the text are not replaced: there is no signer, so they stay as written |

> **Note**
>
> When a predefined document of a signature session has its own `pdfSignatureOptions`, it **replaces** the session's `pdfSignatureOptions` entirely: the
> two are not merged, so repeat the `visualRepresentation` in the document. The exception is `convertToPdfA`, which the document inherits from the session
> (see [PDF/A conversion](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions/pdf-a-conversion)).

The legacy [Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki) APIs that Rest PKI Core still serves (see [Moving from Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/migrating-from-rest-pki#served-apis))
take the same model in the `visualRepresentation` field of the request.

## Text

The `text` object draws a text in the rectangle:

| Field | Description |
| --- | --- |
| `text` | The text, which can have `{{tags}}` (see [below](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#tags)) and line breaks. **Required** whenever `text` is sent: a `text` object without it fails |
| `includeSigningTime` | When `true`, adds a line with the signing time, formatted with the date and time settings of the organization. Default: `false` |
| `fontSize` | The **maximum** font size, in points: the text shrinks, when needed, to fit the rectangle. Default: 12 |
| `horizontalAlign` | `Left` (default) or `Right` |
| `container` | The region of the signature rectangle where the text is drawn, as a [rectangle](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#rectangles) relative to the signature rectangle (not to the page). If omitted, the text can use the whole signature rectangle. The text is aligned to the top of the region |

For instance, to leave a margin of 0.2 around the text:

```json
"text": {
	"text": "Digitally signed by {{name}}",
	"fontSize": 9,
	"includeSigningTime": true,
	"horizontalAlign": "Left",
	"container": { "left": 0.2, "top": 0.2, "right": 0.2, "bottom": 0.2 }
}
```

### Tags

In a signature, the tags in `text` are replaced with data of the signer's certificate (in a [stamp](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp), they stay as written). They are case-sensitive, and an unknown tag stays in the text as written. The most
used:

| Tag | Value |
| --- | --- |
| `{{name}}` | The signer's full name |
| `{{national_id}}` | The signer's national ID (for ICP-Brasil certificates, the holder's CPF) |
| `{{email}}` | The signer's email address |
| `{{issuer_cn}}` | The common name of the certificate's issuer |
| `{{br_cpf_formatted}}` | The holder's CPF, formatted as 000.000.000-00 (ICP-Brasil certificates) |
| `{{br_cpf_masked}}` | The holder's CPF, masked (ICP-Brasil certificates) |

See the [full list of tags](https://docs.lacunasoftware.com/en-us/articles/rest-pki/pades-tags), which are the same as those of Rest PKI.

## Image

The `image` object draws an image in the rectangle, behind the text:

| Field | Description |
| --- | --- |
| `resource` | The image, as `url` (a link the server downloads the image from; the image is cached for about 5 minutes) or `content` (the bytes in Base64). One of them is required, and `content` prevails when both are sent |
| `opacity` | From 0 to 100. Default: 100 |
| `horizontalAlign` | `Left`, `Center` (default) or `Right` |
| `verticalAlign` | `Top`, `Center` (default) or `Bottom` |

The image is scaled to fit the rectangle, keeping its aspect ratio. When the rectangle is wider than the scaled image, `horizontalAlign` places it;
otherwise, `verticalAlign` does.

```json
"image": {
	"resource": { "url": "https://example.com/seal.png" },
	"opacity": 40,
	"horizontalAlign": "Right",
	"verticalAlign": "Center"
}
```

## Position

The `position` object says on which page the signature goes and where on it. It has the page, the units of measurement and **one** of the two ways of
choosing the rectangle: `manual` or `auto`.

| Field | Description |
| --- | --- |
| `pageNumber` | The page: 1 is the first page; negative numbers count from the end (-1 is the last page); 0 appends a new page at the end of the PDF, but only if the PDF has no visible signature yet (otherwise, the last page is used). If omitted, it is 0. A page number beyond the number of pages makes the signature fail |
| `measurementUnits` | `Centimeters` or `PdfPoints` (1/72 of an inch). If omitted, the value of `measurementUnits` in `pdfSignatureOptions` is used and, without it, `Centimeters`. It applies to every measure of the position and to the `container` of the text |
| `manual` | A fixed rectangle on the page: see [Manual positioning](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#manual) |
| `auto` | A region of the page where the signatures are placed one after the other: see [Automatic positioning](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#auto) |
| `pageOptimization` | Deprecated. It also exists in `pdfSignatureOptions`, and the one in the position takes precedence. Measures in centimeters are scaled to a reference paper size that Rest PKI Core estimates from the proportions of the page (Letter, Legal or, otherwise, A4), unless `pageOptimization` says the paper size (`paperSize`, such as `A4` or `Letter`, or `Custom` with `customPaperSize`) and the `pageOrientation`. So, on pages of non-standard size, such as A3, the sizes scale with the page: to have absolute sizes, use `PdfPoints` |

If both `manual` and `auto` are sent, `auto` is used. If neither is, the signature fails.

### Rectangles

Rectangles, such as the `manual` rectangle, the `auto` container and the `container` of the text, are defined by the parameters `left`, `top`, `right`,
`bottom`, `width` and `height`, which are margins relative to what contains the rectangle (the page, or the signature rectangle). You don't set all of
them: what you set decides how the rectangle behaves.

![Rectangle parameters](https://docs.lacunasoftware.com/images/pki-sdk/pades-rectangle.png)

The rectangle, in red, has its margins relative to what contains it. Don't set `left`, `right` and `width` together: horizontally, two of the three (or only `width`) are
enough, and the rest takes up the remaining space. Vertically it works the same way, with `top`, `bottom` and `height` in place of `left`, `right` and
`width`. The examples below show the ways of defining the horizontal dimensions. For more on how rectangles work, see
[Defining a container](https://docs.lacunasoftware.com/en-us/articles/pki-sdk/signatures/pades/visual-rep/containers), from the PKI SDK.

#### Fluid

If you set only `left` and `right`, the rectangle keeps both margins and its width stretches to fill the remaining space.

![Fluid rectangle](https://docs.lacunasoftware.com/images/pki-sdk/fluid.png)

#### Left-anchored

If you set only `left` and `width`, the rectangle keeps the left margin and the width. The right margin takes up the remaining space.

![Left-anchored rectangle](https://docs.lacunasoftware.com/images/pki-sdk/left-anchored.png)

#### Right-anchored

If you set only `right` and `width`, the rectangle keeps the right margin and the width. The left margin takes up the remaining space.

![Right-anchored rectangle](https://docs.lacunasoftware.com/images/pki-sdk/right-anchored.png)

#### Centered

If you set only `width`, the rectangle is centered horizontally with the given width.

![Centered rectangle](https://docs.lacunasoftware.com/images/pki-sdk/centered.png)

### Manual positioning

In `manual`, the rectangle of the signature is fixed, relative to the page. For instance, a rectangle of 7 by 3 cm, with a margin of 2.5 cm from the left
and bottom edges:

```json
"position": {
	"pageNumber": 1,
	"measurementUnits": "Centimeters",
	"manual": { "left": 2.5, "bottom": 2.5, "width": 7, "height": 3 }
}
```

![Manual positioning](https://docs.lacunasoftware.com/images/pki-sdk/pades-visual-rep-manual-pos.png)

### Automatic positioning

In `auto`, you define a **container**, a region of the page, and the size of each signature, and Rest PKI Core places the signatures one after the other
inside the container. It suits documents with several signers, since you don't know the position of each one.

![Automatic positioning: the container and the signature rectangle](https://docs.lacunasoftware.com/images/pki-sdk/auto-positioning.png)

| Field | Description |
| --- | --- |
| `container` | The region of the page that receives the signatures, as a [rectangle](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#rectangles). Required |
| `signatureRectangleSize` | The `width` and `height` of the rectangle of each signature. Required |
| `rowSpacing` | The space between rows. Default: 0 |
| `horizontalDirection` | `LeftToRight` (default) or `RightToLeft`: the direction in which a row fills |
| `verticalDirection` | `TopDown` (default) or `BottomUp`: the direction in which the rows stack |

To choose the position of a signature, Rest PKI Core looks at the last **visible** signature already on the page, regardless of who made it or with which
tool. If the row still has room for another rectangle of the same size, the new signature goes in that row. Otherwise, it goes in a new row, below
(`TopDown`) or above (`BottomUp`) the previous one, separated from it by `rowSpacing`. A row fits as many signatures as the whole number of times the
width of the signature fits in the width of the container. The rows are justified: the columns of a row are spread evenly across the width of the
container, the first against one edge and the last against the other, so there are gaps between the signatures (about 0.73 cm with the
`Footnote` preset, on A4 portrait).

![Automatic positioning: the signatures inside the container](https://docs.lacunasoftware.com/images/pki-sdk/visual-rep-result.png)

> **Warning**
>
> When the container is full, the signature is still made, but **without a visible representation**, and no error is returned. Size the container for the
> number of signers you expect. Rest PKI Core doesn't look for free spaces in the container, nor does it check the other content of the page.

### Presets

The presets return a `position` object with the usual geometry, ready to use as it is, in the `position` field of the visual representation. They are
`GET` routes that need no authentication:

| Route | Parameters | Position |
| --- | --- | --- |
| `GET {endpoint}/Api/PadesVisualPositioningPresets/Footnote` | `pageNumber` (default -1, the last page); `rows` (default 1) | A footnote: the signatures go at the bottom of the page, in a container with margins of 1 cm on the left, right and bottom and a height for the given number of rows, filled from the top, from left to right |
| `GET {endpoint}/Api/PadesVisualPositioningPresets/FootnoteBottomUp` | `pageNumber` (default -1, the last page) | The container is the whole page, minus a margin of 1 cm on each side, and the rows stack from the bottom up |
| `GET {endpoint}/Api/PadesVisualPositioningPresets/NewPage` | None | The signatures go on a new page, with a margin of 1 cm, as in `pageNumber` 0 |

The three presets use signature rectangles of 4.2 x 1.8 cm, with a spacing of 0.3 cm between rows. On an A4 portrait page, that makes 4 signatures per
row.

For example, `GET {endpoint}/Api/PadesVisualPositioningPresets/Footnote?pageNumber=-1&rows=2` returns a position for two rows of signatures at the
bottom of the last page, which fits up to 8 signatures on A4 portrait.

## Examples

### Footnote with a single row

The signatures go at the bottom of the last page, in a single row: on A4 portrait, up to 4 signatures. This is the `Footnote` preset with one row, with a
text and an image. In a signature session:

```text
POST {endpoint}/api/signature-sessions
{
	...
	"pdfSignatureOptions": {
		"visualRepresentation": {
			"text": {
				"text": "Digitally signed by {{name}}\nCPF: {{br_cpf_formatted}}",
				"fontSize": 9,
				"includeSigningTime": true,
				"horizontalAlign": "Left",
				"container": { "left": 0.2, "top": 0.2, "right": 0.2, "bottom": 0.2 }
			},
			"image": {
				"resource": { "url": "https://example.com/seal.png" },
				"opacity": 40,
				"horizontalAlign": "Right",
				"verticalAlign": "Center"
			},
			"position": {
				"pageNumber": -1,
				"measurementUnits": "Centimeters",
				"auto": {
					"container": { "left": 1.0, "right": 1.0, "bottom": 1.0, "height": 1.8 },
					"signatureRectangleSize": { "width": 4.2, "height": 1.8 },
					"rowSpacing": 0.3,
					"horizontalDirection": "LeftToRight",
					"verticalDirection": "TopDown"
				}
			}
		}
	}
}
```

A fifth signer would not have a visible representation: see the [warning above](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pades-visual-representation#auto).

The PKI Suite Samples use this kind of visual representation, with automatic positioning on the last page and a larger signature rectangle:

* [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/spa/PkiSuiteAspNetCoreAngularSample/PkiSuiteAspNetCoreAngularSample.Server/Classes/PadesVisualElements.cs)
* [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/util/restpkicore/PadesVisualElements.java)
* [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/pades-visual-elements-core.js)
* [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/pades-signature-rest-core/start.php)
* [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/pades_signature_rest_core.py)
* [Ruby](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/ruby/rails/app/controllers/pades_signature_rest_core_controller.rb)

### Two rows, for up to 8 signers

For two rows, the height of the container is the height of two rows plus the spacing between them: 2 x 1.8 + 0.3 = 3.9 cm. The rest is the same as in the
previous example, so only the `position` is shown:

```json
"position": {
	"pageNumber": -1,
	"measurementUnits": "Centimeters",
	"auto": {
		"container": { "left": 1.0, "right": 1.0, "bottom": 1.0, "height": 3.9 },
		"signatureRectangleSize": { "width": 4.2, "height": 1.8 },
		"rowSpacing": 0.3,
		"horizontalDirection": "LeftToRight",
		"verticalDirection": "TopDown"
	}
}
```

### A fixed rectangle, in a two-step signature

A signature at a fixed position of the first page, with only the text:

```text
POST {endpoint}/api/signature
{
	"file": {
		"content": "JVBERi0x...",
		"name": "document.pdf"
	},
	"certificate": {
		"content": "MIIG..."
	},
	"signatureType": "Pdf",
	"pdfSignatureOptions": {
		"visualRepresentation": {
			"text": {
				"text": "Signed by {{name}}",
				"includeSigningTime": true
			},
			"position": {
				"pageNumber": 1,
				"measurementUnits": "Centimeters",
				"manual": { "left": 2.5, "bottom": 2.5, "width": 7, "height": 3 }
			}
		}
	}
}
```

## On .NET

The .NET client has no dedicated helpers for the visual representation: you build it with the models of the API, in the `Lacuna.RestPki.Api.PadesSignature`
namespace, and set it in the `VisualRepresentation` property of `PdfSignatureOptions` (or of `StampPdfOptions`, for a stamp). The classes are `PadesVisualRepresentationModel`, with
`PadesVisualTextModel`, `PadesVisualImageModel` (whose `Resource` is a `ResourceContentOrReference`) and `PadesVisualPositioningModel`, which in turn has
a `PadesVisualAutoPositioningModel` or a `PadesVisualRectangleModel` for manual positioning. Their properties have the names of the JSON fields described above, in PascalCase. See how the [.NET sample](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/spa/PkiSuiteAspNetCoreAngularSample/PkiSuiteAspNetCoreAngularSample.Server/Classes/PadesVisualElements.cs) builds one.

## See also

* [Two-step signatures](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/two-step-signatures)
* [Signature sessions](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions)
* [PDF stamps](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp)
* [Tags of the visual representation](https://docs.lacunasoftware.com/en-us/articles/rest-pki/pades-tags)
* [PDF validation marks](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-marking), which are not part of the visual representation of a signature