The place kept for a signature
Keep a spot on the page where an electronic signature will settle, with its name and its frame.
Asked for with
"type": "signature_field"
In plain words
Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.
This is the spot kept at the foot of a contract, the one where the signature will settle. The document comes out with the place ready and named; the signature itself is applied afterwards, by the signer's software or by your own signing chain. You choose where it sits, how big the frame is, and the border that makes it visible on screen. This is what lets you send a contract already fit to sign, with no trip to the printer.
For a developer
Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.
The field is an empty, named signature annotation laid over what the other items drew. It makes do with the pages already there, and rendering draws of it what the border asks for. The request states its name, its rectangle and the settings shared by every field; what later attaches to that spot — certificate, timestamp, signed appearance — belongs to the signing step after rendering. TO BE CHECKED: exactly what the server's signing chain expects of a field laid this way.
Every key, with its default
The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.
Required keys: name, a string; rect. Optional, shared by every field: read_only, required, no_export, booleans at false; background, the colour behind it; border, an object with a required width, a color (default black, given in light) and a style of "solid" (default), {"dashed": {"lengths": …}}, "beveled", "inset" or "underline"; pages, an array of one-based integers, default empty; relative_to. Cross refusal: a CMYK or named-space colour in border.color. It is the shortest field in the schema: it carries its name, its box and the look of its frame.
A whole request that draws it
Post this as it stands and a PDF comes back. Nothing has been left out of it.
{
"items": [
{
"type": "signature_field",
"name": "signature",
"rect": {"llx": 72, "lly": 120, "urx": 272, "ury": 180},
"border": {"width": 0.75}
}
]
}Form fields
A box the reader types into A box the reader ticks A list the reader picks from Several buttons, one answer A button the reader presses
Where to go next
Every key of a request, in one page The other twenty things you can draw
Glossary
- CMYK
- The four inks a printing press lays down: cyan, magenta, yellow and black. A screen mixes light instead, so a document going to a press states its colours in inks, not in screen colours.
- signature
- A seal inside the document that proves two things at once: who approved it, and that not one byte has changed since. A reader shows it as a banner at the top of the page.
- request
- One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.
- server
- A machine that waits for calls and answers them, running day and night with nobody sitting at it. The one that draws documents here holds the engine and hands back the finished pages; the one your website runs on is a different machine doing the same kind of job.
- annotation
- Something laid over a page rather than drawn into it: a clickable rectangle, a box to type in, a button. It sits at its own place on the sheet and is what makes a PDF answer to a click at all.