Anchor placeholders
The [[ls:KIND:ROLE]] marker syntax used by placement="anchors".
placement="anchors" (the default) on
POST /v1/signing-requests finds markers
in your PDF's text layer and places fields on top. This page covers
the marker syntax, what we do with the marker once we find it, and the
rules that produce 400 errors.
Syntax
[[ ls : KIND : ROLE (: FIELD_KEY)? ]]
KIND — signature | initial | date | name | text
ROLE — must match a signers[].role
FIELD_KEY — optional third part: a letter, then letters, digits,
_ - or . — up to 64 characters in all
(e.g. [[ls:text:tenant:person.date_of_birth]])A text or name marker becomes a text box the signer fills in. Its
optional third part is stored as the box's field key; a name
marker without one is keyed person.full_name. A key that asks for the
signer's own details opens the box with them:
| Field key | The box opens with |
|---|---|
person.full_name (or full_name) | The signer's full name |
person.first_name, person.last_name (or first_name, last_name) | That part of the signer's name |
contact.email (or email) | The signer's email address |
company.legal_name (or company) | The company of the workspace address-book contact with the signer's email, if there is one |
role | The role (job title) of that address-book contact, if there is one |
Name and email come from the signing request (the address book can complete
a missing half of the name). The signer can change what the box opens with,
and an empty text box never blocks signing. Any other key only names the
box. The company and job_title you send on a
signer print in the caption
under the signature; they do not fill these boxes.
On a date marker the third part is not a key. This endpoint ignores it.
A date marker stamps the date that signer signs on, taken in the workspace
owner's time zone, in your workspace's house format: 15.03.1990, or
03/15/1990 when the workspace's country (Settings → Company) is the United
States.
Whitespace inside the brackets is tolerated ([[ls:signature:tenant]]
and [[ ls : signature : tenant ]] parse the same). The marker must
live on a single line in the PDF's text layer — line-wrapped
markers are skipped silently, and so is a marker that breaks the syntax
(a FIELD_KEY over 64 characters, say): it is ordinary text, neither placed
nor masked.
Example PDF excerpt
CLIENT — Acme GmbH
[[ls:signature:client_principal]] [[ls:date:client_principal]]
───────────────────────────────── ──────────────
[[ls:name:client_principal]] Date
VENDOR — letssign.now Partners AG
[[ls:signature:vendor_director]] [[ls:date:vendor_director]]
───────────────────────────────── ──────────────
[[ls:name:vendor_director]] DateWhen this contract is POSTed with two signers (client_principal and
vendor_director), the response contains
"anchors": { "found": 6, "fields": 6 } — two signatures, two dates, two
names — and "placement": "anchors". Each field belongs to the signer
whose role its marker names, and each name box opens with its signer's
name.
Rules
A marker can appear once per page per role for signature,
initial, date, and name kinds. Multiple text markers per
page per role are allowed (e.g. multiple inline fill-in-the-blanks).
| Violation | Error | Status |
|---|---|---|
Marker references a role not in signers[] | unknown_role (meta.role, meta.page) | 400 |
Same kind and role twice on the same page (signature, initial, date, name) | duplicate_anchor (meta.role, meta.kind, meta.page) | 400 |
The PDF has markers, but a signer in signers[] has none for their role | signer_has_no_anchor (meta.role) | 400 |
A PDF with no markers at all is not an error, whether you passed
placement="anchors" or left the default: the call falls through to
auto_append and appends a signature page. The response tells you —
"placement": "auto_append" and anchors.found: 0 instead of
"placement": "anchors". By then the invitations are out (unless you sent
send_emails: false), so if a PDF without markers must never go out,
check your generator's output for markers before you send, and
withdraw anything that slipped through.
What happens to the marker
The hash covers what the signer sees. Before presenting the PDF we
draw a white rectangle over each marker, so the signer sees their field on
a clean page rather than the [[ls:…]] text underneath. The document's
SHA-256 — presentedSha256 in the response — is taken after that step:
it is the hash of exactly the file the signers are shown. We don't
keep the file you uploaded or its hash, so keep your own if you ever need
to show the pre-masking original.
The rectangle covers the marker; it does not delete it. The marker's
text is still in the page's content stream, so text extraction
(pdftotext, copy and paste, search in a PDF viewer) can still find
[[ls:…]] in the presented and in the signed PDF. Apart from the
rectangles the file keeps its content — a password-protected PDF is
decrypted first, because it could not be sealed otherwise.