## Signature image configuration overview

SignBox allows placing a **visual signature** inside the signed PDF document. The visual signature combines an optional image with customizable text that displays signer information from the certificate.

Use the `signature_appearance` parameter to define how the signature will look. You can also target specific PDF form fields using `signature_ids`.

## Request parameters

| Parameter | Description | Example |
|  --- | --- | --- |
| `signature_appearance` | JSON object that describes the visual appearance of the signature. | See [Signature appearance object](#signature-appearance-object) below |
| `signature_ids` | Comma-separated list of PDF signature field IDs to sign. Use this when your PDF contains pre-defined signature form fields. | `signature1,signature2` |


## Signature appearance object

The `signature_appearance` object controls text content, positioning, images, date formatting, and layout. All properties are optional; configure only what you need.

### Complete configuration example


```json
{
  "text": [
    "Signed by: %(CN)s",
    "%(EMAIL)s %(L)s %(SUBJECT)s",
    "Date: %(DATE)s"
  ],
  "date": "%d/%m/%Y %H:%M:%S %z",
  "timezone": "America/Guatemala",
  "position": "30,100,165,150",
  "image": "be1cd133-8be5-4346-87de-d40afd90a3b9",
  "horizontal": true,
  "page": 0
}
```

### Parameter reference

| Parameter | Description |
|  --- | --- |
| `text` | Array of text lines to display. Use variables to retrieve data from the signer certificate. Each array element is a separate line. |
| `date` | Date format string. Supports strftime-style placeholders (e.g. `%d/%m/%Y %H:%M:%S`). |
| `timezone` | Timezone for the signature date. Default is UTC. List available timezones with: `timedatectl list-timezones` |
| `position` | Coordinates in points (pt) for signature placement and size: `x1,y1,x2,y2`. Origin is bottom-left of the page. 1px = 0.75pt. |
| `image` | ID of a previously uploaded image to use as the signature graphic. |
| `b64_image` | Image encoded in base64. Use this instead of `image` when you do not pre-upload the image. |
| `qrcode` | URL used to generate a QR code in the signature block. |
| `horizontal` | Boolean. When `true`, arranges image and text horizontally. |
| `page` | Zero-based page index where the signature will be placed. First page is 0. |
| `text_size` | Font size for the signature text. |
| `text_align` | Horizontal alignment of the text (`left`, `center`, or `right`). |
| `reason` | Human-readable reason for signing (e.g. "Contract approval"). |
| `location` | Geographic location associated with the signature. |


## Position coordinate system

The `position` parameter defines a rectangle using four values: `x1,y1,x2,y2`.

- **Origin**: Bottom-left corner of the page (0,0)
- **x1, y1**: Bottom-left corner of the signature area
- **x2, y2**: Top-right corner of the signature area
- **Unit**: Points (pt). Convert from pixels: 1px = 0.75pt


![SignBox signature position coordinate system showing x1,y1,x2,y2 from bottom-left origin](/assets/signbox-signature-position-coordinates.c0611f81769413dfafe12e338ddcb363e6c013619debcefdfc3a66655011fa74.003f76b7.png)

**Example**: `"position": "30,100,165,150"` places a signature 30pt from the left, 100pt from the bottom, with a width of 135pt and height of 50pt.

## Available text variables

Use these placeholders in the `text` array to insert certificate and signature data dynamically.

| Variable | Description |
|  --- | --- |
| `%(CN)s` | Common Name from the signer certificate |
| `%(L)s` | Locality |
| `%(S)s` | State or Province Name |
| `%(OU)s` | Organizational Unit Name |
| `%(E)s` | Email address |
| `%(EMAIL)s` | Email from Subject Alternative Name |
| `%(SUBJECT)s` | Full certificate subject |
| `%(Issuer)s` | Certificate issuer (CA) Common Name |
| `%(DATE)s` | Signature date and time (formatted according to `date` and `timezone`) |
| `%(date)s` | Signature date and time in ISO 8601 format |


**Example text block**:


```json
"text": [
  "Signed by: %(CN)s",
  "%(EMAIL)s",
  "Date: %(DATE)s"
]
```

## Image and QR code options

You can include graphics in the visual signature in three ways:

1. **Pre-uploaded image** (`image`): Upload the image via the SignBox API first and reference it by ID.
2. **Inline base64** (`b64_image`): Provide the image data directly as a base64 string.
3. **QR code** (`qrcode`): Provide a URL; SignBox generates a QR code linking to that URL.


## Related documentation

- [Signatures](/products/namirialpkiaas/signbox/enterprise-documentation/products-and-modules/signatures/signature-levels) — Formats, levels, and configuration scope
- [SignBox signing flow](/products/namirialpkiaas/signbox/enterprise-documentation/get-started/signing-flow) — How signing requests are processed
- [SignBox API reference](/products/namirialpkiaas/signbox/openapi) — Full API specification for signing operations