Add Caption to your Electronic Seal

Caption

You can add a text caption directly inside the Seal field area using the captions parameter on the POST /v3/electronic_seals endpoint (see API reference). This is useful when you want to display a mention, such as the name of a department representative or an internal reference, as part of the seal visual, without placing a separate read_only_text field next to it.

The caption is rendered below the seal image, within the same field area. The font size is calculated automatically so the text fits the available space. If you want to control the line wrapping, adjust the width or the height of the seal field accordingly.

The captions parameter is optional. If omitted, no text is rendered below the seal image.

{
  "fields": [
    {
      "type": "seal",
      "page": 1,
      "height": 200,
      "width": 250,
      "x": 0,
      "y": 0,
      "captions": [
        {
          "text": "Example of a caption"
        }
      ]
    }
  ]
}

To apply no caption, omit the captions key entirely, or pass null as the text value:

"captions": [
  {
    "text": null
  }
]

Rules and constraints:

• caption accepts an array with exactly one entry. Passing more than one item returns an error: Only one caption can be added to seal field.. In the future, the limit could be increased.
• text must not exceed 150 characters. Exceeding this limit returns: Validation error: The string exceeds the maximum allowed length of 150 characters.
• The caption appears even when no image_id is set on the seal, the text is rendered inside the seal field area regardless.
• The caption text is not stored as a reusable asset. You must include it in each seal creation payload where you want it to appear.

⚠️ Sizing advice — make sure your caption is actually visible

As the text is automatically added to the Seal area, a calculation is performed on the fly to manage the text area and the image area (the image’s aspect ratio will not be altered). This means that for each Seal, if the text or image is different, the calculation is performed again.

If the field is set up incorrectly, the text will not appear. We recommend that you prepare the image and text dimensions in the Sandbox to get an idea of how the calculations will work.

• Square image (height = width) → caption only appears if height strictly > width. If width ≥ height, the caption is silently ignored. Once the condition is met, width can be tuned to control text wrapping.
• Rectangular image (width > height) → the logic is inverted: caption is visible only if width strictly > height.

When to use captions vs read_only_text

Use captions when the text is semantically part of the seal itself (e.g., a department name printed under the seal image).
Use read_only_text when you need flexible placement or multiple annotations across the document.