Where to Place Signatures in a Document (API)

Where signatures appear in the document is determined for each signer using the positions field. There are three options.

A. Coordinates

You specify the exact location as a percentage of the page:

"positions": [
    { "x": 50, "y": 80, "page": 0, "relativeWidth": 30 }
]

• x, y — percentages of the page size (0–100): 0, 0 is the top-left corner, 100, 100 the bottom-right. The coordinate defines the top-left corner of the signature rectangle. x: 50, y: 80 = the signature starts horizontally in the middle, near the bottom edge.
• page — the page number, the first page is 0. Negative numbers count from the end: -1 means "at the end of the document" (last page).
• relativeWidth — the width of the signature as a percentage of the page width (optional, default 30).

Multiple signatures for one person

One person can have more than one signature in a document — just add more entries to positions. For example, an initial on the first page and a signature at the end:

"positions": [
    { "x": 85, "y": 92, "page": 0 },
    { "x": 50, "y": 80, "page": 4 }
]

It works the same way with anchor fields — one entry per location:

"positions": [
    { "anchor": "parafa-strana-1" },
    { "anchor": "podpis-zaver" }
]

B. Anchor field in the document (anchor)

You insert a marker (anchor) into the document text and, instead of coordinates, provide the exact same text in anchor. The signature is placed at the marker's location. This is useful when you generate documents and the signature location shifts with the length of the text.

Try it on the sample file kotvy-ukazka.pdf — it has the markers #signi_user_signature# (for the proposer) and #signi_signature# (for the counterparty) in its text:

{
    "people": [
        { "is_proposer": true, "email": "vas@email.cz", "contract_role": "sign",
          "positions": [ { "anchor": "#signi_user_signature#" } ] },
        { "is_proposer": false, "email": "protistrana@email.cz", "contract_role": "sign",
          "first_name": "Jan", "last_name": "Novák", "person_type": "nature",
          "positions": [ { "anchor": "#signi_signature#" } ] }
    ],
    "file": "uploaded_file_key"
}

• The anchor value must match the text in the document literally — if the marker is not found, document processing fails.
• The marker text stays in the document — the signature only covers it. Write the marker in white text so it is not visible in the document.
• It only works for signers (the sign role).

C. No placement — signatures at the end

If you omit positions and set "missing_positions": "append_to_the_end" in settings, the signatures are automatically placed at the end of the document. We do not recommend using this if it can be avoided — the signature sheet changes the document and therefore breaks the initial seal on it. More in the article Document security. (Without this setting, a missing position returns an error.)

The approve role (approver) does not need any placement — nothing is displayed in the document.

Where to go next

• Multiple signers
• Quickstart — your first document for signing via API