Placing fields automatically

Placing fields by hand is fine for one document. For a contract you send every week, or a document AutomaDoc generates, write tags in the document instead: [[sign:Client]] where the client signs, [[date:Client]] where the date goes. When the document is prepared, AutomaDoc finds each tag and puts the field there. API callers who cannot edit the document can use anchors: a field placed relative to text that is already in it.

Text tags

An example in Word

Type the tags as ordinary text where the fields should go:

Signed for the client:

[[sign:Client]]

Name: [[name:Client]]          Date: [[date:Client]]
Company: [[company:Client]]
Purchase order: [[text:Client:PO number;optional]]

[[check:Client:Terms]] I have read and accept the terms.

Signed for the supplier:

[[sign:Supplier;w=180;h=50]]
Initials on every page: [[initials:Supplier]]

When you add this document to a request, it has two slots, Client and Supplier. Give each slot to a recipient and every field of that role goes to that person. From the API, set autoTags: true and give each recipient its slot.

Tags work the same in a PDF, Word, Excel or PowerPoint file, and in an AutomaDoc template: generation leaves square brackets alone, so a document generated from a template with tags arrives in a request with its fields ready to place. That is why tags use [[ ]] and not the { } of template placeholders.

Grammar

[[ kind : role ]]
[[ kind : role : label ]]
[[ kind : role ; option ; option ]]
[[ kind : role : label ; option ]]

Kind (any case) says what the field is:

Kind	Also written	Field
sign	signature	Signature
initials	initial	Initials
name		Name
date		Date signed (filled automatically)
text		Text
check	checkbox	Checkbox
company		Company
email		Email

Role is the slot the field belongs to: 1 to 60 letters, digits, accent marks or underscores, in any alphabet (Client, Witness_1, 客户). No spaces. Case counts: Client and client are two slots. A # followed by digits after the role is reserved for AutomaDoc’s own use.

Label, optional, is 1 to 100 characters shown to the signer as the field’s name, for example [[text:Client:PO number]]. It may not contain [, ], ; or :.

Options, each after a ;, in any case:

Option	Meaning
w=180	Width in points (1 point is 1/72 inch), from 8 to 1000, up to two decimals
h=50	Height in points, from 8 to 1000
optional	The signer may leave the field empty
required	The signer must fill it (the default)

Spaces and line breaks are allowed around every part, so [[ sign : Client ]] works, and so does a tag that wraps onto a second line between two of its parts. A line break inside a word (in the middle of Client, say) breaks the tag.

A tag is at most 200 characters from [[ to ]]. Longer than that, or with no closing ]], it is ordinary text and is ignored.

Where the field lands

The field’s top-left corner is the tag’s top-left corner. Its size is the tag’s w and h, or otherwise the field’s default (in points: signature 160 × 48, initials 64 × 40, checkbox 14 × 14, email 180 × 20, date 110 × 20, the other text fields 160 × 20). Without h, a field is never shorter than the tag’s text. A field that would run off the page is moved onto it.

So leave room to the right of and below each tag: a signature field reaches 48 points (about 1.7 cm) down from the top of its tag.

Note

The tag stays in the document. AutomaDoc does not remove or cover it: the page everyone sees and signs shows the tag as you wrote it, and the signature or value is drawn over it.

When something is wrong

A [[…]] that does not follow the grammar is never guessed at: it stays on the page as text, no field is made, and the sender is warned, with the tag as written (the first 50 per document). The usual causes are a missing role, a space inside the role, an unknown kind or option, or a size outside 8 to 1000.

Other limits:

• at most 500 tags per page are read, and 500 per document; past that, the rest are ignored with a warning;
• only text the PDF actually contains is searched: a scanned page is a picture, and tags in it are not found;
• a tag whose role was not given to any recipient makes no field. A signer left without any field cannot be sent the request.

Applying tags again replaces the fields made from tags. Fields you placed by hand stay.

Anchors from the API

An anchor places a field relative to text already in the document, such as “Client signature:”. It is for documents you cannot edit. Anchors are part of POST /api/v1/envelopes (see the Envelopes API). Here the request is sent as multipart/form-data: this JSON in a part named envelope, the PDF in a part named contract.

{
  "title": "Service agreement",
  "documents": [{ "file": "contract" }],
  "recipients": [
    { "key": "client", "role": "signer", "name": "Ana Lim", "email": "ana@example.com" }
  ],
  "anchors": [
    { "anchor": "Client signature:", "recipient": "client", "type": "signature", "offsetY": 14 },
    { "anchor": "Date:", "occurrence": 2, "recipient": "client", "type": "date_signed", "offsetX": 30, "offsetY": -2 }
  ],
  "send": true
}

Property
anchor	The text to find, 1 to 200 characters. Required.
recipient	The key of a recipient in the same request. Required.
type	signature, initials, name, date_signed, text, checkbox, company or email. Required.
occurrence	"all" (the default) or a number: the 1st, 2nd… match across the whole request.
offsetX, offsetY	Points from the top-left corner of the matched text, from -2000 to 2000. Positive goes right and down. Default 0.
w, h	Size in points, from 8 to 1000. Default: the field type’s size.
required	true by default.
label	Shown to the signer as the field’s name.

A request may hold up to 50 anchors.

How text is matched

• Exactly and case-sensitively: Signature: does not match signature: or Signature.
• Any run of spaces, tabs or line breaks in the anchor matches any run of them in the document, since PDF text keeps no reliable spacing. Spaces at the start or end of the anchor are ignored.
• Matches never overlap.
• Occurrences count across the request in reading order: documents in their order, then page by page, top to bottom, left to right. "occurrence": 2 is the second match anywhere in the request, not the second on each page.
• At most 200 matches per anchor. More is taken as a mistake: write a longer anchor.

An anchor that matches nothing makes no field, and the document records an anchor_not_found warning. As with tags, an anchor’s field that would run off the page is moved onto it, and a signer left with no field at all stops the request from being sent: GET /api/v1/envelopes/:id then reports why in sendError.

You can combine fields by coordinates, tags (autoTags) and anchors in one request, up to 500 fields in all.