Generate reports

Generate a report

Renders a document by merging a specified template with provided JSON data.
It supports both template IDs and version IDs.

New Features in V5:

• Constant Template ID: Multiple versions of a template can be associated with a single Template ID. Carbone checks the deployedAt timestamp to determine which version of the template is actively deployed. The version with the most recent deployedAt timestamp is selected for document generation.
• Unified Workflow: Streamline your workflow by combining template upload, document generation, and download into a single API call. For instance, call the endpoint as follows: POST /render/template?download=true and provide the template as a base64-encoded string in the request body.
• PDF Converter Options: When generating PDFs, you can now choose from multiple converter engines for optimal results. Use the converter option with convertTo:"pdf".
• HTML-to-PDF Rendering: Carbone now supports high-fidelity HTML-to-PDF conversion, enabling you to generate professional PDFs directly from HTML templates. Use the converter option with convertTo: "pdf" and select the Chrome engine C for robust rendering of modern web content, including dynamic layouts, CSS, and JavaScript.

Request header

{
  // Required Pass your API token here (string)
  "authorization"       : "Bearer API_TOKEN",
  // Required Content-type (string)
  "content-type"        : "application/json",
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
  // Webhook for asynchronous rendering (string)
  // Called by Carbone when the report is generated
  "carbone-webhook-url" : "http://your-url",
  // Webhook custom headers (string)
  "carbone-webhook-header-X" : "headers value"
}

Request body

{
  // Required Data that is merged into the template with tags {d.} (array|object)
  "data"         : {},
  // Output file format. More info (string|object)
  "convertTo"    : "pdf",
  // When the "convertTo" field is set to "pdf", use this option to specify the converter engine. The following values are supported: Set "L": LibreOffice (default), the best balance between performances and document compatibility. Set "O": OnlyOffice, Ideal for office documents (DOCX, XLSX, PPTX). Set "C": Chromium, High-fidelity HTML-to-PDF conversion, perfect for web-based templates.
  "converter": "L",
  // Provide a template file directly in your API request, use the "/render/template" endpoint and include the template content as a base64-encoded string in the request body.
  "template": "BASE64_ENCODED_TEMPLATE_CONTENT",
  // Convert document dates to a timezone. More info (string)
  "timezone"     : "Europe/Paris",
  // Locale of the generated document. More info (string)
  "lang"         : "en-us",
  // Extra data object that can be merged into the template with tags {c.} (object)
  "complement"   : {},
  // Predefined alias TODO put the link to the alais doc in designer (string)
  "variableStr"  : "{#def = d.id}",
  // Static or dynamic file name returned on the `content-disposition` header. More info (string)
  "reportName"   : "{d.date}.odt",
  // List of enumerations with to use with convEnum formatter (object)
  "enum"         : {
    "ORDER_STATUS" : ["open", "close"],
    "SPEED" : {
      "10" : "slow",
      "20" : "fast"
    }
  },
  // Localization dictionary to use with Carbone tags `{t( )}`. More info (object)
  "translations" : {
    "fr-ca" : {"one":"un" },
    "es"    : {"one":"uno"}
  },
  // Currency source coming from your JSON data. More info (string)
  "currencySource" : "EUR",
  "currencyTarget" : "USD",
  // More info (object)
  "currencyRates"  : {
    "EUR" : 1,
    "USD" : 1.1403
  },
  // Force the report to recompute pagination and table of contents (boolean)
  "hardRefresh": false,
  // Generate multiple reports with one template and multiple JSON objects. More info (string)
  "batchSplitBy" : "d.items",
  // From v5+, the output format for batch processing. More info (string)
  "batchOutput" : "zip"
}

Request Query Parameters

Parameter	Type	Description
download	Boolean	Downloads the generated document directly. This bypasses the need to call GET /render/{renderId} to download the generated document, as the document is not stored in Carbone servers but returned directly as a file stream, and the content type will reflect the type of the generated document. Example Usage: POST /render/{templateId-or-versionId}?download=true

Response

On success, by default a JSON response with content-type application/json containing the render ID is returned, which is a unique identifier for the generated document. If the query parameter download=true is used, the response body will be the file itself, and the content type will reflect the type of the generated document.

	Status Code	Body
	200	{ "success" : true, "data": { "renderId": "" } } or File Stream, if the query parameter download=true is used.
	400	{ "success" : false, "error" : ""Content-Type" header is not "application/json""}
	400	{ "success" : false, "error" : "Invalid templateId"}
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	404	{ "success" : false, "error" : "Template not found"}
	413	{ "success" : false, "error" : "Content too large, the JSON size limit is X MB"}
	422	{ "success" : false, "error" : "Missing "data" property in body"}
	500	{ "success" : false, "error" : "Error while rendering template"}
	500	{ "success" : false, "error" : "Error while setting up the webhook"}

Curl Example

curl  --location --request POST 'https://api.carbone.io/render/TEMPLATE_ID' \
      --header 'carbone-version: 5' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer API_TOKEN' \
      --data-raw '{ "data": { "firstname": "John", "lastname": "Wick" }, "convertTo": "pdf" }'

Output filename

With Carbone, even the generated report filename is a template!

This filename is returned content-disposition header when the generated report is fetched with GET /report/:renderId.

Output file type

By default, if convertTo is undefined, the output file type is the same as the input template file type.

The table below list all accepted convertTo values according to the input template file type.

And some output file types can have additional options. See the dedicated documentation

• for pdf
• for jpg/png
• for csv

Template Type	convertTo
document	pdf, docx, odt, bib, doc, doc6, doc95, docbook, docx7, fodt, html, latex, odt, ooxml, ott, psw, rtf, sdw, stw, sxw, text, txt, uot, vor, xhtml, jpg, jpeg, png, epub, md, svg, webp, pages
spreadsheet	pdf, xlsx, ods, csv, dbf, dif, fods, html, ooxml, ots, pxl, slk, stc, sxc, uos, xhtml, xls, xls5, xls95, xlt, xlt5, xlt95, numbers, parquet, json
presentation	pdf, pptx, odp, bmp, emf, eps, fodp, gif, html, jpg, met, odg, pbm, pct, pgm, png, ppm, pwp, ras, sti, svg, svm, swf, sxi, tiff, uop, wmf, xhtml, otp, potm, pot, pps, ppt, webp
web	pdf, etext, html10, html, mediawiki, sdw3, sdw4, sdw, txt, text10, text, vor4, vor
graphics	bmp, emf, eps, fodg, gif, html, jpg, met, odd, otg, pbm, pct, pdf, pgm, png, ppm, ras, std, svg, svm, swf, sxd, tiff, vor, wmf, xhtml, webp, pub, cdr

Notes:

• Export to xhtml to embed images in html

Multi-timezone

Some dates formatter like formatD or formatI adapt the inserted date in the template according to the timezone.

List of accepted timezone (Column TZ identifier) : https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Multi-language

Many text, dates, numbers formatters like formatN, formatD, formatI adapt the inserted date in the template according to the locale.

Also, the lang parameter is used to select the correponding translations when the Carbone tag {t()} is used for multi-lingual reports.

List of supported locales: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js

You can support multiple languages in your report by using translations formatters.

Multi-currency

You can also create templates that support multiple devices depending on the locale.

The option is used by formatC to convert the currency based on the currencyTarget and currencyRates. Target currency when the document is generated. The option is used by formatC to convert the currency based on the currencySource and currencyRates. Currency exchange rates for conversions from currencySource to currencyTarget. Learn more

PDF options

Options can be passed for PDF conversion. In this case, convertTo have to be an object with formatName set to pdf and formatOptions with options.

{
  "convertTo" : {
    "formatName"    : "pdf",
    "formatOptions" : {
      "EncryptFile"          : true,
      "DocumentOpenPassword" : "QWERTY1234",
      "Watermark"            : "Watermark Carbone.io"
    }
  }
}

The following options can be passed to formatOptions:

Option Category	LibreOffice	Chrome	OnlyOffice
All PDF Options
Security Options
Watermark Option

• All PDF Options: All the options listed above (General, Compression, Quality, View, etc.) can be used.
• Security Options: Options such as password protection and file encryption.
• Watermark Option: Option to add a watermark to each page.

For most advanced PDF controls, use the LibreOffice converter.
If you are using Chrome or OnlyOffice, only "Security" and "Watermark" options are supported.

JPG/PNG options

It is possible to export jpg or png images with options (list bellow).

Here is an example of exporting a JPG image with options:

{
  "convertTo": {
    "formatName" : "jpg",
    "formatOptions": {
      "Quality"   : 50,
      "ColorMode" : 1
    }
  }
}

CSV options

During CSV conversion, the following elements can be changed: separator, delimiters and the character set. convertTo have to be an object with formatName set to csv and formatOptions with options. characterSet can be one these options : https://wiki.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Filter_Options

{
  convertTo : {
    formatName    : 'csv',
    formatOptions : {
      fieldSeparator : '+',
      textDelimiter  : '"',
      characterSet   : '76' // utf-8
    }
  }
}

Watermark options

Carbone supports adding one or multiple text watermarks to every page of a generated PDF. Watermarks are defined inside the formatOptions object when convertTo is set to pdf.

Two fields are available:

• Watermark (string) — Legacy field, still supported. Renders a single centered watermark at 45° with default styling. Use this for simple use cases or backward compatibility.
• Watermarks (array) — New field introduced in v5.3.0. Accepts up to 5 watermark objects, each fully configurable. Both fields can be used simultaneously.

{
  "convertTo": {
    "formatName": "pdf",
    "formatOptions": {
      // Legacy: single centered watermark (backward compatible)
      "Watermark": "CONFIDENTIAL",
      // New in v5.3.0: array of watermark objects
      "Watermarks": [
        {
          "text": "Confidential - Page {#PAGE_NUMBER} / {#PAGE_TOTAL}",
          "anchor": "topLeft",
          "offsetX": 10,
          "offsetY": 10,
          "rotation": -45,
          "color": "#000000",
          "size": 64,
          "opacity": 0.21,
          "font": "Helvetica",
          "fromPage": 1,
          "toPage": 10
        }
      ]
    }
  }
}

Watermark object properties

The following properties apply to each watermark object defined inside the Watermarks array. They are not available on the legacy Watermark string field.

All properties except text are optional.

Property	Type	Default	Description
text	string	—	Required. The watermark label. Between 1 and 2000 characters. Supports {#PAGE_NUMBER} and {#PAGE_TOTAL} variables for dynamic page numbering.
anchor	string	center	Position on the page. Accepted values: topLeft, top, topRight, left, center, right, bottomLeft, bottom, bottomRight.
offsetX	number	0	Horizontal offset in points (pt) from the anchor. In PDFs, the origin is bottom-left, so positive values move right.
offsetY	number	0	Vertical offset in points (pt) from the anchor. Positive values move up.
rotation	number	45 for center, 0 for others	Rotation angle in degrees, between -360 and 360. For non-center anchors, only 0, 90, or -90 are allowed.
color	string	#000000	Watermark text color in #RGB or #RRGGBB format (e.g. #ff0000, #f00).
size	number	Auto for center, 12 for others	Font size in points (pt), between 1 and 2000.
opacity	number	0.1 for center, 1 for others	Opacity between 0 (invisible) and 1 (fully opaque).
font	string	Helvetica	Font family. Accepted values: Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic.
fromPage	integer	1	First page (1-based) on which the watermark is applied.
toPage	integer	Last page	Last page (1-based) on which the watermark is applied. Defaults to all remaining pages.

Dynamic page numbering

Use {#PAGE_NUMBER} and {#PAGE_TOTAL} in the text field to insert the current page number and total page count into the watermark.

{
  "text": "Draft - Page {#PAGE_NUMBER} of {#PAGE_TOTAL}"
}

Asynchronous jobs

When the report is huge, we highly recommend employing the asynchronous rendering system. This method offers a longer rendering timeout of 5 minutes, surpassing the 60-second limit of the synchronous API.

Carbone will notify your application/service at a custom URL as soon as the document is generated.

How to use this system?

1. Prepare your server to accept POST requests at a webhook endpoint. For experimentation, https://webhook.site/ is a convenient option.
2. Send a request to POST /render/:templateId with the HTTP header carbone-webhook-url: https://my-custom-webhook/my-custom-url
3. (From version 4.23.0) If your webhook url needs authentication or a specific header, you can configure it by adding the header carbone-webhook-header-X. Ex : carbone-webhook-header-authorization: my-secret
4. Upon report completion, Carbone will invoke your webhook endpoint, sending a JSON object that includes the renderId. The response object is the same as the response from the synchronous method.

Carbone automatically retries (one retry) to call your webhook for the following errors:

• Status Code Errors: 408, 429, 502, 503, 504, 521, 522, 524
• Socket Errors: ETIMEDOUT, ECONNRESET, EADDRINUSE, ECONNREFUSED, EPIPE, ENOTFOUND, ENETUNREACH, EAI_AGAIN
• Request Timeout (16 seconds max)

Batch processing

Starting from version 4.20.0, Carbone introduces the capability to generate multiple reports in one go using a single HTTP request, with the same template. This feature streamlines the creation of reports, especially when dealing with bulk data, by returning a compressed ZIP (or PDF) file that contains all generated reports.

Batch processing is particularly useful for generating personalized documents, such as letters or invoices, for multiple recipients simultaneously.

Batch processing is enabled if all of the following conditions are met

• Include the batchSplitBy attribute in the POST /render/:templateId request (see below).
• Utilize asynchronous job processing by setting the carbone-webhook-url HTTP header in your request (see above).
• Only for Cloud: Ensure the data payload contains a non-empty array with up to 100 objects (= 100 reports)
• Only for On-Premise: The global configuration parameter nbReportMaxPerBatch is greater than 0.

API Request Example

To initiate batch processing, send a JSON object structured as follows:

{
  "data"         : {
    "letters" : [
      { "id" : 1, "name" : "John"   },
      { "id" : 2, "name" : "David"  },
      { "id" : 2, "name" : "Steeve" }
    ]
  },
  // The result will be a ZIP file of multiple PDFs
  "convertTo"    : "pdf",
  // Batch processing option.
  "batchSplitBy" : "d.letters",
  // From v5+, can be "zip" (default), or "pdf"
  "batchOutput" : "zip"
}

batchSplitBy determines how the batch is split. Accepted values:

• "d" if data is an array of objects, resulting in one report per object.
• "d.myCustomField" to select a direct child array of "data", resulting in one report per object in that array.

batchOutput determines the output file type. Accepted values:

• zip to get an archive of all generated reports.
• pdf to get a concatenation of generated PDFs (only possible if convertTo = "pdf").

Template Writing Methods

When writing templates for batch processing, you can employ two approaches. Carbone automatically detects the method used.

1. Direct child access: Write the template directly at the d.letters[] level, using placeholders for each data field.

    {d.id} {d.name}

2. Array access: Write the template at the root level d. For each report, Carbone generates an array containing a single object, thereby producing one report for every object within d.letters.

    {d.letters[i].id}    {d.letters[i].name}
    {d.letters[i+1].id}

Download report with single API call

Add a new option to the API endpoint POST /render/:idTemplate. The query parameter ?download=true can be used to download the rendered report directly.

When this option is used, the file is not stored on our servers. A single API call is enough to download the file. There is no need to call GET /render.

Important: The Content-Disposition header changes based on the HTTP status: If the status is 200 (OK):

  Content-Disposition: 'attachment; filename="report.pdf"'
  Content-Type: 'application/pdf'

For all other statuses: The response remains in application/json format as before.