Design

Digital signatures

Place signature fields in a template, then send their page and coordinates from the API response to your e-signature provider.
ENTERPRISE FEATURE Available for:
Carbone Cloud
Carbone On-premise
Embedded Carbone JS v5.00.0+

Electronic signatures are in Beta on Carbone v5.

Overview

Mark where each person signs in your template: when Carbone renders the PDF, the API response gives the page and the position of every signature field. Send the PDF and these positions to your e-signature provider (DocuSign, Yousign, Documenso, SignWell, Subnoto...). Nobody places fields by hand, even when a longer document pushes the signatures to the next page.

Write a :sign tag where each person signs or dates the document.
Render the template to PDF, with the carbone-version: 5 header.
Read the page, x and y of each field in the render response.
Send the PDF and the positions to your provider.

:sign

{d.signer:sign} marks a signature field. Its value comes back untouched in the response, next to the position: store in it what your provider needs to invite the signer.

Field	Example	Use
`type`	`"signature"`, `"date"`, `"initials"`	Kind of field the provider draws
`name`	`"Emma Johnson"`	Name of the signer
`email`	`"emma.johnson@bluebird.example"`	Address of the invitation

Carbone requires none of these fields: the value can be any JSON value. Use the names and types of your provider API, and add what it needs, such as order for the signing order. A document holds up to 999 fields. Write the tag in a loop to get one field per item.

Example: sign a service agreement

Acme sends a service agreement to Bluebird Logistics: the client signs and dates it, then Acme countersigns. The template holds three tags, {d.client.signer:sign}, {d.client.signedOn:sign} and {d.provider.signer:sign}, written in Arial with a white opening {.

DataTemplateResultResponse

data.jsonDownload

{
  "reference": "SA-2026-0142",
  "date": "November 12, 2026",
  "service": {
    "name": "Managed IT support",
    "startDate": "December 1, 2026",
    "term": "12 months",
    "monthlyFee": 1450
  },
  "provider": {
    "company": "Acme Corporation",
    "address": "200 Main Street, Boston, MA 02110",
    "signer": {
      "type": "signature",
      "name": "Jane Smith",
      "email": "jane.smith@acme.example"
    },
    "signerTitle": "Account Manager"
  },
  "client": {
    "company": "Bluebird Logistics",
    "address": "350 Fifth Avenue, New York, NY 10118",
    "signer": {
      "type": "signature",
      "name": "Emma Johnson",
      "email": "emma.johnson@bluebird.example"
    },
    "signerTitle": "Operations Director",
    "signedOn": {
      "type": "date",
      "name": "Emma Johnson",
      "email": "emma.johnson@bluebird.example"
    }
  }
}

template.docxDownload

DOCX template of a service agreement with three :sign tags in the signature block, each opening bracket in white, outlined by dashed boxes drawn on the screenshot

report.pdfDownload

PDF generated by Carbone: the service agreement before signature, with dashed boxes drawn on the screenshot at the three positions of the response

response.jsonDownload

{
  "success": true,
  "data": {
    "renderId": "pWcRYV0nHJ0b8Oblqr08bgcmVwb3J0.pdf",
    "signatures": [
      {
        "data": {
          "type": "signature",
          "name": "Jane Smith",
          "email": "jane.smith@acme.example"
        },
        "page": 1,
        "x": 308,
        "y": 416
      },
      {
        "data": {
          "type": "signature",
          "name": "Emma Johnson",
          "email": "emma.johnson@bluebird.example"
        },
        "page": 1,
        "x": 88,
        "y": 416
      },
      {
        "data": {
          "type": "date",
          "name": "Emma Johnson",
          "email": "emma.johnson@bluebird.example"
        },
        "page": 1,
        "x": 114,
        "y": 524
      }
    ]
  }
}

The dashed boxes mark the tags on the Template tab, and the positions returned in the response on the Result tab. They are drawn on the screenshots only: the PDF shows no field, each tag became an invisible marker. The Response tab is the JSON returned by the render request.

Response

The render response lists the fields in data.signatures, next to the renderId of the PDF:

Property	Description
`data`	Value of the tag, as sent. Missing when the value is undefined.
`page`	Page of the field. The first page is 1.
`x`	Distance from the left edge of the page to the left of the tag, in points (1 pt = 1/72 inch).
`y`	Distance from the top edge of the page to the top of the tag, in points.

The origin is the top-left corner of the page: x grows to the right, y grows down. An A4 page is 595 by 842 points. Subnoto uses the same unit and origin: send x and y as they are, and page as a string.
The array does not follow the reading order of the document: match each field by its data, not by its index.
Download the PDF with GET /render/{renderId}, like any report. With ?download=true, the response is the file, without positions.

Usage rules

Send the carbone-version: 5 header and render to PDF ("convertTo": "pdf"). Other output formats return no positions and keep the markers.
Write each :sign tag in Arial or Calibri. Carbone replaces the tag with a marker, the character ʕ and three digits (ʕ000), and finds it in the PDF: with a font that lacks ʕ, such as Georgia, the render fails with Signature position No. 000 was not found in the generated PDF.
Give the opening { of each tag the color of the background: white on a white page. The marker takes the format of this first character, so it does not show in the PDF (it stays in the text layer). This format change also gives the exact x of a tag written after text on the same line: without it, x points to the start of that text.
Leave room below and to the right of each tag: the provider draws each field from the position of its tag.
Keep every field that has a value. When a condition removes a tag whose value is set, the render fails. To skip a field, leave its value undefined.

Tutorials

Automate secure electronic signatures with Carbone and Subnoto: generate a contract with Carbone, then sign it confidentially with Subnoto. See also the Subnoto integration.
Add a DocuSign signature to your documents, with Make.

Reference

Place the fields with the API of your provider: