Supported File Formats
Templates and documents travel to and from ReportingCloud as Base64 strings inside JSON, and each endpoint of the Web API decides which formats it reads and which it returns. The tables below follow the Web API reference endpoint by endpoint and point out where the endpoints differ, so that you can check a format before you build on it.
Return Formats
The endpoints that create a document take the format of the result in the returnFormat query parameter, in upper or lower case. Without it, they return PDF. Its values:
returnFormat | Format | merge | findandreplace | convert | append |
|---|---|---|---|---|---|
PDF | Adobe PDF | Yes | Yes | Yes | Yes |
PDFA | PDF/A, the ISO standard for long-term archiving | Yes | Yes | Yes | Yes |
DOCX | Microsoft Word, Office Open XML | Yes | Yes | Yes | Yes |
DOC | Microsoft Word, binary format | Yes | Yes | Yes | Yes |
RTF | Rich Text Format | Yes | Yes | Yes | Yes |
HTML | XHTML with inline CSS styles and embedded images | Yes | Yes | Yes | Yes |
TX | The internal format of TX Text Control | Yes | Yes | Yes | Yes |
TXT | Plain text | Yes | Yes | Yes | Yes |
What the table does not show:
- TXT since 2019. The blog article ReportingCloud: Extract Plain Text from Adobe PDF, MS Word or HTML Documents introduced
TXTin 2019 for every endpoint that returns documents, and the .NET, PHP, Java and Ruby SDKs accept it for merge as well. - Plain text from PDF. With
TXT,POST /v1/document/convertextracts the text of a PDF, DOCX or HTML document. - PDF/A depends on the plan. The pricing page lists PDF/A export for the Extreme plan only, and a trial account can't create PDF/A:
PDFAanswers403with the text "Setting is not supported in this license. An Extreme license is required". See Plans and Licensing. - Watermarks. Documents created in test mode carry a "TEST MODE" watermark, except plain text. The documents of a trial account carry the ReportingCloud logo at the top left of the page, in test mode or not.
Formats per Endpoint
| Endpoint | Accepts | Returns |
|---|---|---|
| document/merge | A template from the storage, in RTF, DOC, DOCX or TX, or in the request body, in RTF, DOC, DOCX, TX or HTML, and JSON merge data | An array of documents in the returnFormat: one for all records, or one per record with append=false |
| document/findandreplace | A template from the storage, in RTF, DOC, DOCX or TX, or in the request body, in RTF, DOC, DOCX, TX, HTML, PDF, XLSX or plain text, and pairs of strings to find and replace | One document in the returnFormat |
| document/convert | A document in RTF, DOC, DOCX, HTML, PDF, TX, XLSX or plain text | One document in the returnFormat |
| document/append | Documents in RTF, DOC, DOCX, HTML, PDF, TX, XLSX or plain text; the PHP SDK accepts DOC, DOCX, HTML, PDF, RTF and TX files | One document in the returnFormat |
| document/thumbnails | A document in DOC, DOCX, PDF, TX, XLSX, RTF or HTML | Page images in the imageFormat |
| document/share | The name of a template in the storage | An encrypted document name for the viewer widget of ReportingCloud |
| templates/upload | A template in DOC, DOCX, RTF or TX | Stores the template |
| templates/download | The name of a template in the storage | The template as a Base64 string |
| templates/info | The name of a template in the storage | JSON with the merge fields, the merge blocks and the user-defined document properties of the template |
| templates/thumbnails | The name of a template in the storage | Page images in the imageFormat |
| processing/review/trackedchanges | A document in RTF, DOC, DOCX or TX | JSON with the tracked changes |
| processing/review/removetrackedchange | A document in RTF, DOC, DOCX or TX | The changed document in TX format |
What the table does not show:
- Templates in the storage are RTF, DOC, DOCX and TX documents:
templates/uploadrefuses other formats. A template in the request body can also be HTML, anddocument/findandreplacereads a PDF, XLSX or plain text template as well. - XLSX is accepted by
document/convert,document/appendanddocument/thumbnails, and as a template in the request body ofdocument/findandreplace. - TX output of removetrackedchange.
processing/review/removetrackedchangealways returns TX. To get another format, send the result todocument/convert. - Several documents. Only
document/mergereturns an array of documents.document/findandreplace,document/convertanddocument/appendreturn a single one, as one Base64 string.
Image Formats
Images appear in two places, as page thumbnails that the Web API renders and as images that your merge data puts into a template:
| Where | Formats |
|---|---|
Page thumbnails of document/thumbnails and templates/thumbnails, set with the imageFormat parameter | PNG by default, or JPG, GIF or BMP |
| Image placeholders in a template, filled with Base64 image data from the merge data | JPG, PNG, BMP and GIF |
The thumbnail endpoints also take a zoomFactor from 10 to 400 percent, 100 by default, and a page range in fromPage and toPage. Thumbnails shows how to render pages, and Images how to merge images into placeholders.
Fonts
The ReportingCloud servers have Windows fonts, such as Arial, Calibri and Times New Roman, and many Google Fonts, but not every Google Font: Inter, Roboto Condensed, Roboto Mono and Ubuntu, for example, are missing. The GET /v1/fonts/list endpoint returns the names of the available fonts as a JSON array of strings, and the template editor lists the same fonts in the font list of its Home tab. When you create a template in MS Word and upload it, check with this list that the template uses only available fonts. Template Design covers templates from MS Word.