# Converting Documents

> Turn DOCX into PDF or PDF/A, HTML into Word and PDF into plain text with document/convert: returnFormat values, test runs, the quota, curl and .NET.

- **Product:** ReportingCloud
- **Section:** Documentation
- **Kind:** Topic
- **Path:** ReportingCloud > Document Processing > Converting Documents
- **1797 words**
- **Web URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/converting/
- **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/converting/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/converting/llms-full.txt

---

`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](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/convert/post/llms-full.txt):

| Part of the request | Content |
|---|---|
| Body | The source document as a Base64 string in a JSON string, with the content type `application/json`. The service recognizes RTF, DOC, DOCX, HTML, PDF, TX and XLSX by their content and reads anything else as plain text |
| `returnFormat` | Optional. The format to create: `PDF`, `PDFA`, `RTF`, `DOC`, `DOCX`, `HTML`, `TXT` or `TX`, in any letter case. Without it, the result is PDF |
| `test` | Optional. `true` runs a test conversion, described below |
| Response | The converted document as a Base64 string in a JSON string |

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](https://docs.textcontrol.com/reporting-cloud/overview/licensing/#test-mode) is not available with a Free account. [Plans and Licensing](https://docs.textcontrol.com/reporting-cloud/overview/licensing/llms-full.txt) lists the quota of each plan.

The processing time of a request is limited to 60 seconds, as [Processing Time Limit](https://docs.textcontrol.com/reporting-cloud/document-processing/errors/#processing-time-limit) explains; a typical document takes less than 5 seconds. Every request also needs the `Authorization` header that [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt) describes.

### Convert a Document With curl

The following commands convert *invoice.docx* to PDF:

```bash
# 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:

```csharp
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](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/#authenticate-with-the-sdks) 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](https://docs.textcontrol.com/reporting-cloud/sdks/llms-full.txt) 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:

| `returnFormat` | Creates |
|---|---|
| `PDF` | Adobe PDF |
| `PDFA` | PDF/A, the ISO standard format for archiving PDF documents |
| `DOCX` | Microsoft Word, Office Open XML |
| `DOC` | Microsoft Word 97-2003 |
| `RTF` | Rich Text Format |
| `HTML` | HTML |
| `TX` | The internal format of TX Text Control, the engine behind ReportingCloud |
| `TXT` | Plain text |

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](https://docs.textcontrol.com/reporting-cloud/overview/file-formats/llms-full.txt) 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:

```bash
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](https://docs.textcontrol.com/reporting-cloud/document-processing/appending/llms-full.txt): combine several documents into one and convert the result in the same request.
- [Thumbnails](https://docs.textcontrol.com/reporting-cloud/document-processing/thumbnails/llms-full.txt): render the pages of a document as images instead.
- [Mail Merge](https://docs.textcontrol.com/reporting-cloud/mail-merge/llms-full.txt): create documents from a template and JSON data.
- [Errors and Status Codes](https://docs.textcontrol.com/reporting-cloud/document-processing/errors/llms-full.txt): what to do when a request is refused.

---

## Nearby

- **Previous:** [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt)
- **Next:** [Appending Documents](https://docs.textcontrol.com/reporting-cloud/document-processing/appending/llms-full.txt)