Converting Documents

POST /v1/document/convert turns one document into another format: a DOCX into a PDF for sending, an HTML page into a Word document, a PDF into plain text for a search index. The document goes to the Web API as a Base64 string, and the converted document comes back the same way, so any language that sends HTTP requests can convert files without a library of its own.

How Converting Works

The endpoint is POST /v1/document/convert:

The body is the JSON string alone, not an object around it. A request without a document in the body is answered with 400 Bad Request.

Every successful conversion adds one document to the document quota of your account, whatever the size of the document. With test=true, the conversion is not counted, the result carries a "TEST MODE" watermark and the request is handled with lower priority; test mode is not available with a Free account. Plans and Licensing lists the quota of each plan.

The processing time of a request is limited to 60 seconds, as Processing Time Limit explains; a typical document takes less than 5 seconds. Every request also needs the Authorization header that Authentication describes.

Convert a Document With curl

The following commands convert invoice.docx to PDF:

# Wrap the Base64 string of the document in a JSON string
base64 -w 0 invoice.docx | jq -Rs . > document.json

curl "https://api.reporting.cloud/v1/document/convert?returnFormat=PDF" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @document.json \
  --output converted.json

# Decode the Base64 string of the response
jq -r . converted.json | base64 -d > invoice.pdf

The commands work as follows:

• base64 -w 0 encodes the file on one line, and jq -Rs . turns the encoded text into a JSON string with quotes. Writing the body to a file keeps a large document off the command line.
• --data-binary @document.json sends the file unchanged as the request body.
• jq -r . removes the quotes of the JSON string in the response, and base64 -d decodes it into invoice.pdf.

Convert a Document With .NET

The .NET SDK, the NuGet package TXTextControl.ReportingCloud, sends the same request from C#. The following console application converts invoice.docx to PDF:

using TXTextControl.ReportingCloud;

ReportingCloud rc = new ReportingCloud(
    Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

byte[] document = File.ReadAllBytes("invoice.docx");

// Convert the document and save the result
byte[] pdf = rc.ConvertDocument(document, ReturnFormat.PDF);
File.WriteAllBytes("invoice.pdf", pdf);

The code works as follows:

• The ReportingCloud constructor takes the API key, as Authentication explains.
• ConvertDocument takes the document as a byte array and a ReturnFormat value, and returns the converted document as a byte array. The SDK does the Base64 encoding and decoding.
• A third argument, test, sends the request as a test run: rc.ConvertDocument(document, ReturnFormat.PDF, true).
• When the Web API refuses the request, ConvertDocument throws an ArgumentException whose message is the response body.

The PHP SDK has the same call as convertDocument($documentFilename, $returnFormat). It takes the path of the file instead of its content, accepts the extensions .doc, .docx, .html, .pdf, .rtf and .tx, and returns the converted document as a binary string. The pages of the SDKs section list the methods of every SDK.

Choose the Target Format

Set returnFormat, or the ReturnFormat value in .NET, to the format your application needs:

For example, ?returnFormat=DOCX turns an HTML page into a Word document. The pricing page lists PDF/A export for the Extreme plan only, and a trial account creates no PDF/A and puts the ReportingCloud logo on its documents. Supported File Formats lists the formats of every endpoint.

Extract Plain Text

With returnFormat=TXT, the endpoint returns the text of a document without its formatting. This extracts the text of a PDF, a DOCX or an HTML document, for example to index it for a search or to check its content. A PDF has to be a digitally created one, which contains its text, not a scanned image of the pages:

base64 -w 0 document.pdf | jq -Rs . > document.json

curl "https://api.reporting.cloud/v1/document/convert?returnFormat=TXT" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @document.json \
  --output converted.json

jq -r . converted.json | base64 -d > document.txt

In .NET, pass ReturnFormat.TXT to ConvertDocument and read the returned bytes as text. Like every other conversion, a text extraction counts as one document against the quota.

Next Steps

• Appending Documents: combine several documents into one and convert the result in the same request.
• Thumbnails: render the pages of a document as images instead.
• Mail Merge: create documents from a template and JSON data.
• Errors and Status Codes: what to do when a request is refused.