Add a signature field

A signature field is a crucial component in PDF documents that contain an electronic signature. It serves as a designated space where users can apply their signatures electronically. Signature fields can be either invisible or visible. Invisible signature fields aren’t visible on a document surface, while visible signature fields have a visual representation on a document, enabling users to see and interact with them.

The choice between a visible or invisible signature field depends on whether you want the signature field to have a visual representation or if you prefer for it to remain hidden from the document viewer.

An invisible signature field is still a cryptographically valid signature.

How Document Engine creates signature fields

Unlike client-side SDKs where you manually create signature form fields, Document Engine automatically creates signature fields as part of the signing process. When you call the sign endpoint, Document Engine will create the signature field if it doesn’t already exist.

There are three methods to control how signature fields are created.

Method 1: Create a named signature field

When signing a document, you can specify a formFieldName in your sign request. If the field doesn’t exist, Document Engine will create it automatically at the specified position:

Terminal window
curl -X POST http://localhost:5000/api/documents/{document_id}/sign \
  -H "Authorization: Token token=<API token>" \
  -H "Content-Type: application/json" \
  -d '{
    "signatureType": "cms",
    "formFieldName": "mySignatureField",
    "position": {
      "pageIndex": 0,
      "boundingBox": {
        "left": 50,
        "top": 50,
        "width": 150,
        "height": 30
      }
    },
    "appearance": {
      "mode": "signatureAndDescription",
      "showSignDate": true,
      "showWatermark": true
    },
    "signatureMetadata": {
      "signerName": "John Doe",
      "signatureReason": "Contract Approval",
      "signatureLocation": "San Francisco, CA"
    }
  }'

This method is recommended when you want to reference the signature field by name, or if multiple signatures need to be added to the same field.

Method 2: Create a signature field at a position

If you don’t specify formFieldName, the signature field will be created at the specified position:

Terminal window
curl -X POST http://localhost:5000/api/documents/{document_id}/sign \
  -H "Authorization: Token token=<API token>" \
  -H "Content-Type: application/json" \
  -d '{
    "signatureType": "cms",
    "position": {
      "pageIndex": 0,
      "boundingBox": {
        "left": 50,
        "top": 50,
        "width": 150,
        "height": 30
      }
    }
  }'

Method 3: Create an invisible signature field

For an invisible signature, omit both formFieldName and position:

Terminal window
curl -X POST http://localhost:5000/api/documents/{document_id}/sign \
  -H "Authorization: Token token=<API token>" \
  -H "Content-Type: application/json" \
  -d '{
    "signatureType": "cms"
  }'

An invisible signature is still cryptographically valid, but it has no visual representation on the document.

Key parameters

  • formFieldName — Name of the signature form field. If it doesn’t exist, it will be created at the position you specify.
  • position — Required if creating a visible signature. Contains pageIndex and boundingBox.
  • boundingBox — Object with left, top, width, and height properties in PDF points (1/72 inch).
  • signatureType — Type of signature to create (typically "cms" for cryptographic message syntax).
  • appearance — Optional configuration for how the signature appears visually.
  • signatureMetadata — Optional metadata such as signer name, reason, and location.

Important notes

  • Either formFieldName or position must be provided for visible signatures.
  • When creating a new signature field, you can provide both formFieldName and position to create a named, visible signature field at the specified location. If a signature field with the specified formFieldName already exists in the document, omit the position parameter to sign the existing field. Providing both when the field already exists may result in an error.
  • Document Engine handles the signature field creation automatically — you don’t need to create the field separately before signing.

For more information on configuring the visual appearance of digital signatures, refer to the guide on configuring digital signature appearance.