eSign Tags Reference

Tags are interactive fields that you place on PDF documents to specify where signers should add their signatures, initials, dates, and other information. The Stewart Sign API uses JSON to define tag positions, types, and assignments to participants.

This guide provides a complete reference for all supported eSign tag types and how to implement them in your transactions.

tip

New to eSign? Start with our Create Your First eSignature Transaction guide to learn the basics, then return here for detailed tag specifications.

---

Understanding the Coordinate System

The PDF coordinate system uses the bottom-left corner as the origin (0, 0). This is important when positioning tags on your documents.

• X-axis: Increases from left to right
• Y-axis: Increases from bottom to top
• Page numbering: 0-indexed (page 0 is the first page, page 1 is the second, etc.)

Tag Positioning

Each tag requires four coordinate values:

• x: The horizontal position of the tag's bottom-left corner
• y: The vertical position of the tag's bottom-left corner
• width: The tag's width, extending to the right from the x coordinate
• height: The tag's height, extending upward from the y coordinate

{
  "x": 100,      // 100 points from left edge
  "y": 150,      // 150 points from bottom edge
  "width": 150,  // 150 points wide
  "height": 34,  // 34 points tall
  "page": 0      // First page of document
}

Coordinate Tips

Many PDF viewers display coordinates when you hover over the document. Remember to adjust for the bottom-left origin if your tool uses a top-left origin.

---

Data Requirements

To add tags to your eSign documents, you need:

1. Participants - A list of signers with unique IDs, names, and email addresses
2. Tags - Specifications for each interactive field including:
   • Tag type (signature, date, text field, etc.)
   • Position on the PDF (x, y coordinates, width, height)
   • Page number
   • Assignment to a participant (signerId)

---

Participant Object

Each participant in your transaction must be defined with the following properties:

Schema

{
  signerId: string         // Required - Unique UUID for this participant
  firstName: string        // Required - Participant's first name
  middleName?: string      // Optional - Participant's middle name
  lastName: string         // Required - Participant's last name
  email: string           // Required - Valid email address
  type: string            // Required - "signer"
}

Example

{
  "signerId": "cb08d3ad-6199-465d-88c0-e73d96c50c54",
  "firstName": "John",
  "middleName": "Malcolm",
  "lastName": "Gills",
  "email": "john.gills@example.com",
  "type": "signer"
}

Participant Types

• signer: A person who will sign the document

---

JsonTag Object

The JsonTag object defines the type, position, and properties of each tag on your document.

Complete Schema

{
  type: TagType            // Required - Type of tag (see TagType enum below)
  x: number               // Required - Bottom-left x coordinate
  y: number               // Required - Bottom-left y coordinate
  width: number           // Required - Tag width in points
  height: number          // Required - Tag height in points
  page: number            // Required - 0-indexed page number
  signerId?: string       // Required - UUID of assigned participant
  required?: boolean      // Optional - Whether tag must be completed (default: false)
  fontSize?: number       // Optional - Font size for text-based tags (default: 12, min: 9)
  dateFormat?: string     // Optional - Format for date tags (default: "MM/DD/YYYY")
}

Field Reference

Field	Required	Default	Description
type	✅	-	The type of tag from the TagType enum
x	✅	-	The bottom-left x coordinate of the tag
y	✅	-	The bottom-left y coordinate of the tag
width	✅	-	The width of the tag extending to the right
height	✅	-	The height of the tag extending upward
page	✅	-	Page number (0 = first page, 1 = second page, etc.)
signerId	✅	-	The UUID of the participant this tag is assigned to
required	❌	false	If true, the tag must be filled before completion
fontSize	❌	12	Font size for text-based tags (minimum 9)
dateFormat	❌	"MM/DD/YYYY"	Date format for DATETEMPLATE tags

Example

{
  "type": "SIGNHERETAGTEMPLATEANNOTATION",
  "x": 100,
  "y": 150,
  "width": 150,
  "height": 34,
  "page": 2,
  "signerId": "cb08d3ad-6199-465d-88c0-e73d96c50c54",
  "required": true,
  "fontSize": 12
}

---

Supported Tag Types

The following tag types are supported for eSign transactions:

Signature & Initials

Tag Type	Purpose	Recommended Size
SIGNHERETAGTEMPLATEANNOTATION	Main signature field where signers apply their signature	150 × 34
INITIALHERETAGTEMPLATEANNOTATION	Initial field where signers add their initials	60 × 30

Example - Signature Tag:

{
  "type": "SIGNHERETAGTEMPLATEANNOTATION",
  "x": 100,
  "y": 200,
  "width": 150,
  "height": 34,
  "page": 0,
  "signerId": "signer-uuid-123",
  "required": true
}

Example - Initials Tag:

{
  "type": "INITIALHERETAGTEMPLATEANNOTATION",
  "x": 500,
  "y": 750,
  "width": 60,
  "height": 30,
  "page": 1,
  "signerId": "signer-uuid-123"
}

---

Text & Name Fields

Tag Type	Purpose	Auto-filled
FULLNAMETEMPLATE	Automatically fills the signer's full name	✅ Yes
EMAILTEMPLATE	Automatically fills the signer's email address	✅ Yes
TEXTANNOT	Static text annotation (non-editable display text)	❌ No
FREEFORMTEMPLATE	General text field template	❌ No

Example - Full Name (Auto-filled):

{
  "type": "FULLNAMETEMPLATE",
  "x": 100,
  "y": 180,
  "width": 150,
  "height": 20,
  "page": 0,
  "signerId": "signer-uuid-123",
  "fontSize": 11
}

Example - Email (Auto-filled):

{
  "type": "EMAILTEMPLATE",
  "x": 100,
  "y": 160,
  "width": 200,
  "height": 20,
  "page": 0,
  "signerId": "signer-uuid-123",
  "fontSize": 11
}

Example - Free-form Text Input:

{
  "type": "FREEFORMTEXTTAGTEMPLATEANNOTATION",
  "x": 100,
  "y": 400,
  "width": 200,
  "height": 25,
  "page": 0,
  "signerId": "signer-uuid-123",
  "fontSize": 11
}

Example - Static Text Annotation:

{
  "type": "TEXTANNOT",
  "x": 100,
  "y": 500,
  "width": 300,
  "height": 20,
  "page": 0,
  "fontSize": 10
}

Text Field Differences

• FULLNAMETEMPLATE: Auto-populated with the participant's full name from their profile
• EMAILTEMPLATE: Auto-populated with the participant's email address from their profile
• FREEFORMTEXTTAGTEMPLATEANNOTATION: Editable field where signers can type custom text
• TEXTANNOT: Display-only text that cannot be edited by signers

---

Date Fields

Tag Type	Purpose	Format Options
DATETEMPLATE	Inserts the signing date with customizable format	Multiple formats available

Available Date Formats:

Format String	Example Output
MM/DD/YYYY	01/31/2020
DD/MM/YYYY	31/01/2020
MM/DD/YY	01/31/20
DD/MM/YY	31/01/20
MMMM do, yyyy	March 31, 2023

Example:

{
  "type": "DATETEMPLATE",
  "x": 270,
  "y": 150,
  "width": 100,
  "height": 20,
  "page": 0,
  "signerId": "signer-uuid-123",
  "dateFormat": "MM/DD/YYYY"
}

---

Input & Selection Fields

Tag Type	Purpose	Interaction	Recommended Size
CHECKHERETAGTEMPLATEANNOTATION	Checkbox field for yes/no selections	Toggle on/off	20 × 20
RADIOBUTTONTAGTEMPLATEANNOTATION	Radio button for single-choice selection	Select one option	20 × 20
DROPDOWNTAGTEMPLATEANNOTATION	Dropdown menu for selecting from predefined options	Select from list	150 × 30

Example - Checkbox:

{
  "type": "CHECKHERETAGTEMPLATEANNOTATION",
  "x": 100,
  "y": 350,
  "width": 20,
  "height": 20,
  "page": 0,
  "signerId": "signer-uuid-123"
}

Example - Radio Button:

{
  "type": "RADIOBUTTONTAGTEMPLATEANNOTATION",
  "x": 100,
  "y": 300,
  "width": 20,
  "height": 20,
  "page": 0,
  "signerId": "signer-uuid-123"
}

Dropdown Tag:

{
  "type": "DROPDOWNTAGTEMPLATEANNOTATION",
  "x": 350,
  "y": 500,
  "width": 150,
  "height": 25,
  "page": 0,
  "signerId": "signer-uuid-123",
  "customData": {
    "dropdownOptions": ["Option A", "Option B", "Option C"]
  }
}

---

Complete Examples

Example 1: Single Signer with Basic Tags

This example shows a simple employment agreement with a signature, date, and printed name:

{
  "documents": [
    {
      "id": "391866a6-8ebb-4533-b6ab-c7bb4d6fbd38",
      "StoragePath": "14a00c39-af89-47ee-b26c-f0bc523c270e/EmploymentAgreement.pdf",
      "title": "Employment Agreement",
      "sessionType": "esign",
      "tags": [
        {
          "type": "SIGNHERETAGTEMPLATEANNOTATION",
          "x": 100,
          "y": 150,
          "width": 150,
          "height": 34,
          "page": 2,
          "signerId": "signer-uuid-123",
          "required": true
        },
        {
          "type": "DATETEMPLATE",
          "x": 270,
          "y": 150,
          "width": 100,
          "height": 20,
          "page": 2,
          "signerId": "signer-uuid-123",
          "dateFormat": "MM/DD/YYYY"
        },
        {
          "type": "FULLNAMETEMPLATE",
          "x": 100,
          "y": 190,
          "width": 150,
          "height": 20,
          "page": 2,
          "signerId": "signer-uuid-123",
          "fontSize": 11
        }
      ]
    }
  ],
  "participants": [
    {
      "id": "signer-uuid-123",
      "signerId": "signer-uuid-123",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com",
      "type": "signer"
    }
  ]
}

---

Example 2: Multiple Signers with Multi-Page Tags

This example shows a sales contract with two signers (buyer and seller) with signatures on different pages:

{
  "documents": [
    {
      "id": "doc-uuid-456",
      "StoragePath": "path/to/SalesContract.pdf",
      "title": "Sales Contract",
      "sessionType": "esign",
      "tags": [
        {
          "type": "SIGNHERETAGTEMPLATEANNOTATION",
          "x": 50,
          "y": 100,
          "width": 150,
          "height": 34,
          "page": 0,
          "signerId": "buyer-uuid",
          "required": true
        },
        {
          "type": "FULLNAMETEMPLATE",
          "x": 50,
          "y": 140,
          "width": 150,
          "height": 20,
          "page": 0,
          "signerId": "buyer-uuid"
        },
        {
          "type": "SIGNHERETAGTEMPLATEANNOTATION",
          "x": 250,
          "y": 100,
          "width": 150,
          "height": 34,
          "page": 0,
          "signerId": "seller-uuid",
          "required": true
        },
        {
          "type": "FULLNAMETEMPLATE",
          "x": 250,
          "y": 140,
          "width": 150,
          "height": 20,
          "page": 0,
          "signerId": "seller-uuid"
        },
        {
          "type": "INITIALHERETAGTEMPLATEANNOTATION",
          "x": 500,
          "y": 750,
          "width": 60,
          "height": 30,
          "page": 1,
          "signerId": "buyer-uuid"
        },
        {
          "type": "INITIALHERETAGTEMPLATEANNOTATION",
          "x": 500,
          "y": 700,
          "width": 60,
          "height": 30,
          "page": 1,
          "signerId": "seller-uuid"
        },
        {
          "type": "DATETEMPLATE",
          "x": 200,
          "y": 50,
          "width": 100,
          "height": 20,
          "page": 2,
          "dateFormat": "MMMM do, yyyy"
        }
      ]
    }
  ],
  "participants": [
    {
      "id": "buyer-uuid",
      "signerId": "buyer-uuid",
      "firstName": "John",
      "lastName": "Buyer",
      "email": "john.buyer@example.com",
      "type": "signer"
    },
    {
      "id": "seller-uuid",
      "signerId": "seller-uuid",
      "firstName": "Mary",
      "lastName": "Seller",
      "email": "mary.seller@example.com",
      "type": "signer"
    }
  ]
}

---

Example 3: Form with Input Fields

This example demonstrates checkboxes, radio buttons, and text input fields:

{
  "documents": [
    {
      "id": "form-uuid-789",
      "StoragePath": "path/to/ApplicationForm.pdf",
      "title": "Application Form",
      "sessionType": "esign",
      "tags": [
        {
          "type": "FREEFORMTEXTTAGTEMPLATEANNOTATION",
          "x": 100,
          "y": 400,
          "width": 200,
          "height": 25,
          "page": 0,
          "signerId": "applicant-uuid",
          "fontSize": 11
        },
        {
          "type": "CHECKHERETAGTEMPLATEANNOTATION",
          "x": 100,
          "y": 350,
          "width": 20,
          "height": 20,
          "page": 0,
          "signerId": "applicant-uuid"
        },
        {
          "type": "RADIOBUTTONTAGTEMPLATEANNOTATION",
          "x": 100,
          "y": 300,
          "width": 20,
          "height": 20,
          "page": 0,
          "signerId": "applicant-uuid"
        },
        {
          "type": "RADIOBUTTONTAGTEMPLATEANNOTATION",
          "x": 150,
          "y": 300,
          "width": 20,
          "height": 20,
          "page": 0,
          "signerId": "applicant-uuid"
        },
        {
          "type": "DROPDOWNTAGTEMPLATEANNOTATION",
          "x": 100,
          "y": 520,
          "width": 150,
          "height": 30,
          "signerId": "applicant-uuid",
          "customData": {
            "dropdownOptions": ["Full-time", "Part-time", "Contract"]
          }
        },
        {
          "type": "SIGNHERETAGTEMPLATEANNOTATION",
          "x": 100,
          "y": 100,
          "width": 150,
          "height": 34,
          "page": 0,
          "signerId": "applicant-uuid",
          "required": true
        }
      ]
    }
  ],
  "participants": [
    {
      "id": "applicant-uuid",
      "signerId": "applicant-uuid",
      "firstName": "Alex",
      "lastName": "Johnson",
      "email": "alex.johnson@example.com",
      "type": "signer"
    }
  ]
}

---

Best Practices

Tag Placement and Sizing

Recommended Minimum Sizes:

• Signatures: 150 × 34 points
• Initials: 60 × 30 points
• Checkboxes/Radio buttons: 20 × 20 points
• Dropdowns: Width 150+ points, height 25-35 points
• Text fields: Height 20-30 points, width as needed
• Date fields: 100 × 20 points minimum

Placement Tips:

• Ensure tags don't overlap existing document content
• Leave adequate spacing between tags (at least 10 points)
• Align related tags horizontally or vertically for a clean appearance
• Test on actual PDFs to verify positioning

---

Required Fields

Use the required: true property for critical fields that must be completed:

{
  "type": "SIGNHERETAGTEMPLATEANNOTATION",
  "required": true,
  // ... other properties
}

Guidelines:

• Mark signature fields as required
• Balance required vs optional fields for better user experience
• Consider making date fields required alongside signatures

---

Working with Multiple Signers

When your document has multiple signers:

1. Assign unique UUIDs to each participant
2. Clearly assign tags using the signerId property
3. Consider signing order in your workflow
4. Group related tags visually on the document
5. Test the experience from each signer's perspective

---

Coordinate Calculation Tips

Finding Coordinates:

1. Use a PDF viewer that displays cursor coordinates
2. Remember the origin is at bottom-left (0, 0)
3. If your tool shows top-left origin, subtract from page height
4. Test with a few tags first before placing many

Common Pitfalls:

• ❌ Forgetting about the bottom-left origin
• ❌ Using negative coordinates
• ❌ Placing tags outside page boundaries
• ❌ Using incorrect page numbers (remember: 0-indexed!)

---

Integration with API

Creating a Transaction with Tags

Use the POST /transactions endpoint with your tags defined in the documents array:

curl -X POST "https://api.sign.stewart.com/transactions" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "id": "doc-uuid",
      "StoragePath": "path/to/document.pdf",
      "title": "Contract",
      "sessionType": "esign",
      "tags": [
        {
          "type": "SIGNHERETAGTEMPLATEANNOTATION",
          "x": 100,
          "y": 150,
          "width": 150,
          "height": 34,
          "page": 0,
          "signerId": "signer-uuid",
          "required": true
        }
      ]
    }],
    "participants": [{
      "id": "signer-uuid",
      "signerId": "signer-uuid",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "type": "signer"
    }]
  }'

For a complete guide, see Create Your First eSignature Transaction.

---

Troubleshooting

Common Errors

Invalid UUID Format:

// ❌ Incorrect
"signerId": "123"

// ✅ Correct
"signerId": "cb08d3ad-6199-465d-88c0-e73d96c50c54"

Page Number Issues:

// ❌ Incorrect (pages are 0-indexed)
"page": 1  // This is the SECOND page

// ✅ Correct (first page)
"page": 0

Coordinates Out of Bounds:

// ❌ Tag extends beyond page width
{
  "x": 500,
  "width": 200,  // If page is 612 points wide, this extends beyond
  "page": 0
}

// ✅ Tag fits within page
{
  "x": 400,
  "width": 150,
  "page": 0
}

Mismatched Signer IDs:

// ❌ Tag references non-existent participant
{
  "signerId": "wrong-uuid",  // Not in participants array
  // ...
}

// ✅ Tag references existing participant
{
  "signerId": "cb08d3ad-6199-465d-88c0-e73d96c50c54",  // Matches participant
  // ...
}

---

Validation Checklist

Before submitting your transaction, verify:

• All participant signerId values are valid UUIDs
• All tag signerId values match a participant's signerId
• Page numbers are 0-indexed and within document range
• All coordinates (x, y) are positive numbers
• Width and height values are positive
• Required tags include required: true
• Date tags specify a valid dateFormat (if not using default)
• Font sizes are at least 9 (if specified)
• Dropdown tags have at least one option in dropdownOptions
• Dropdown tags are wide enough to display option text (≥ 150 points recommended)

---

Quick Reference

Complete TagType Enum

enum TagType {
  // Signature & Initials
  SIGNHERETAGTEMPLATEANNOTATION      // Signature field
  INITIALHERETAGTEMPLATEANNOTATION   // Initials field
  
  // Text & Names
  FULLNAMETEMPLATE                   // Auto-filled full name
  EMAILTEMPLATE                      // Auto-filled email address
  TEXTANNOT                          // Static text annotation
  FREEFORMTEXTTAGTEMPLATEANNOTATION  // Fillable text field
  
  // Dates
  DATETEMPLATE                       // Signing date
  
  // Inputs
  CHECKHERETAGTEMPLATEANNOTATION     // Checkbox
  RADIOBUTTONTAGTEMPLATEANNOTATION   // Radio button
  DROPDOWNTAGTEMPLATEANNOTATION      // Dropdown selection menu
}

---

💬 Need Help?

Contact the Stewart Sign Support Team for technical assistance or integration guidance.