Skip to main content
When you add an element to a document - a signing field, text box, checkbox, or radio group - you have to tell NSEV where on the page it goes. There are three ways to do that, and you can mix them within a single document:
  1. Explicit coordinates - you give a page, a position, and a size.
  2. Text markers - a short code embedded in the document text marks the spot, and its size.
  3. Existing PDF form fields - you reference a field already present in the uploaded PDF by its name.
This page covers all three. For what each element type is and how elements relate to actors and documents, see The package model. For the calls that create elements, see Send a document for signing and Instant package.
Markers and existing PDF fields are resolved against the uploaded document, so it is recommended to create those elements at document-upload time. After a document conversion, a referenced marker or field may no longer exist.

​
Explicit coordinates

Supply a Location and Dimensions and the element is placed exactly where you say.
Location has three required fields:
  • Page - the page the element is on. Pages are 1-based: 1 is the first page, 2 the second, and so on. 0 must not be used. To count from the end of the document, use negative integers: -1 is the last page, -2 the second-to-last, and so on.
  • Top - distance from the top edge of the page. Minimum 0.
  • Left - distance from the left edge of the page. Minimum 0.
Top and Left are measured from the top-left of the page in points (1 point = 1/72 inch). Dimensions has a required Width and Height. The minimum size depends on the element type: The maximum for both width and height is 999999.
A single document must not contain more than 30 signing fields.
A radio group is positioned per button rather than as a whole: each option in the group carries its own Location and Dimensions.

​
Text markers

A text marker is a short code written into the document’s text. When NSEV processes the document it finds the marker, reads the element’s identifier and size from it, and places the element there - so you do not supply coordinates yourself. This is useful when the people authoring the documents control field placement, or when the same template is applied to documents whose layout varies. The marker encodes the element’s id, height, and width. The exact format depends on the element type, and signing fields use a different prefix (#) from form fields (@).

​
Signing field marker

Regex: #[a-zA-Z]+(?:\d*\.)?\d+_(?:\d*\.)?\d+_(?:\d*\.)?\d+# For example, a signing field with id sig1, height 70, and width 112 is marked in the document text as:

​
Form field markers

Form fields (text box, checkbox, radio group) use the @ prefix and a # terminator. There is a generic form-field marker plus type-specific variants for text boxes and checkboxes:
Regexes:
  • Generic form field: @[a-zA-Z]+(?:\d*\.)?\d+_(?:\d*\.)?\d+_(?:\d*\.)?\d+#
  • Text box: @[a-zA-Z]+(?:\d*\.)?\d+_TB_(?:\d*\.)?\d+_(?:\d*\.)?\d+#
  • Checkbox: @[a-zA-Z]+(?:\d*\.)?\d+_CB_(?:\d*\.)?\d+_(?:\d*\.)?\d+#
For example, a text box with id name1, height 20, and width 200:
A radio group cannot be placed with a text marker. Place a radio group with explicit coordinates (one Location and Dimensions per option) or by referencing an existing PDF form field.

​
Marker matching when creating from a template

When a package is created from a template whose elements are matched to documents by markers, the SingleMarkerMatchPerElement parameter on POST /packages controls how each element definition is consumed as documents are confirmed:
  • false (the default, or null): an element definition can be matched by markers in multiple documents, and cleanup of any remaining unplaced elements is deferred.
  • true: each element definition can be matched by only one marker during document confirmation, and the definition is removed once it has been placed.
See Templates for the full template flow.

​
Existing PDF form fields

If the uploaded PDF already contains form fields you can attach an element to one of them with FieldId instead of giving coordinates or a marker. The FieldId is the name of the PDF field, and it must be unique within the document. To be referenceable by FieldId, the PDF field’s name must follow the NSEV naming convention: a signature field’s name must match the signature-field pattern (# prefix) and a form field’s name must match the form-field pattern (@ prefix). A field whose name does not follow the convention cannot be targeted by FieldId - so the fields you intend to reference must be named accordingly when the PDF is prepared.
As with markers, the prefix pattern differs between signature fields and form fields:
  • Signature field (placed as a SigningField): #[a-zA-Z]+(?:\d*\.)?\d+
  • Form field - checkbox, text box, or radio group: @[a-zA-Z]+(?:\d*\.)?\d+
This is the one way a radio group can be attached to an existing field rather than placed by coordinate.
The names of existing signature and text fields in an uploaded PDF must be alphanumeric - only letters and numbers, no accented characters, slashes, or dots. There is also a tenant-configurable rule under which uploaded text fields whose name matches the configured Text Field format are converted to empty signature fields. Both behaviours are covered in Gotchas → PDF input pitfalls.

​
Choosing an approach

  • Use explicit coordinates when your integration owns the layout and you know exactly where each field belongs. It is the most direct and works for every element type.
  • Use text markers when the documents are authored by someone else who can place the markers, or when one template is applied to documents whose layouts differ. Not available for radio groups.
  • Use existing PDF form fields when the uploaded PDF was already prepared with named fields and you want to map elements onto them.

​
Next steps