What is a Smart Anchor?

A Smart Anchor is a text-based placeholder that allows to automatically position Fields (such as Signature Fields, Text Fields, or Checkboxes) on a Document, eliminating the need to manually define coordinates.

Instead of specifying X/Y positions and page numbers when adding a Field with an API endpoint, you embed the Smart Anchor inside your document, and Yousign detects and adds the corresponding Field during document processing.

Each Smart Anchor follows a specific pattern to generate the corresponding field. For example: {{s1|signature|85|37}} for a Field of type Signature.

To keep them hidden in the final document, Smart Anchors should match the Document background color.

How Smart Anchors work

Step-by-step guide

1. Insert a Smart Anchor in your document, using a predefined pattern. For this example, we’ll add a Signature Field using this anchor {{s1|signature|85|37}}

   

   This will create a Signature Field for the first Signer (s1), with a width of 85px and a height of 37px.

   The anchor font color is white (the same as the background) so it can’t be seen by the document reader, but can be interpreted by Yousign.

2. Upload the Document to your Signature Request.
   When uploading a Document via API, you must enable anchor parsing by setting parse_anchors to true.
   Once uploaded, the response will include a total_anchors field indicating the number of detected anchors.

3. Yousign scans the Document when you activate the Signature Request, recognizes the Smart Anchor, and adds the Field to the Signature Request at that exact location. The Field is automatically linked to the correct Signer, based on the Signer index in the pattern.

⚠️

Limitations and errors management

To maintain performance, the usage of Smart Anchors is only possible on Documents fitting the following criteria:

• Only works on 50MB Documents or below with 150 pages or less.
• Smart Anchors must be written in a single line.
• If an anchor references a non-existent Signer, the field will not be created: for instance, specifying “s2” for aa Signature Request with only one Signer won’t work.

If any of those criteria is not matched, no error will be sent but the Smart Anchors won't be applied.

The recommended font for better recognition is Arial with a font size between 10px and 14px.

Why use Smart Anchors?

Smart Anchors are especially useful when you can plan Fields placements during Document creation.