# Converting Documents

> Convert DOCX, RTF, HTML and PDF to PDF, PDF/A, DOCX, DOC, RTF, HTML, TX or plain text with the convert endpoint and flatten form fields, from curl or .NET.

- **Product:** DS Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** DS Server > Document Processing > Converting Documents
- **2031 words**
- **Web URL:** https://docs.textcontrol.com/ds-server/document-processing/converting/
- **LLMs URL:** https://docs.textcontrol.com/ds-server/document-processing/converting/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/ds-server/document-processing/converting/llms-full.txt

---

A DOCX upload that has to be archived as PDF, an HTML page that should become a Word document, an RTF file from an old system: the convert endpoint of the DocumentProcessing Web API turns a document into another format in one request. You send the document as a Base64 string, name the format you want in the `returnFormat` parameter and receive the converted document, again as Base64.

### How Converting Works

The endpoint is [POST /documentprocessing/document/convert](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/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` |
| `returnFormat` | The format to create: `PDF`, `PDFA`, `DOCX`, `DOC`, `RTF`, `HTML`, `TX` or `TXT`. The default is `PDF` |
| `flattenFormFields` | `true` replaces the form fields of the document by their current values. The default is `false` |
| 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 JSON object as the body is refused with `400` "One or more validation errors occurred.", and the error names the cause: "The JSON value could not be converted to System.String." The source can be RTF, DOC, DOCX, HTML, PDF or TX, the TX Text Control format.

Every request needs an access token, as [Authentication](https://docs.textcontrol.com/ds-server/document-processing/authentication/llms-full.txt) describes. The samples use the service URL `http://localhost:5000` and the token in the variable `TOKEN`.

### Convert a Document With curl

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

```bash
DS=http://localhost:5000
TOKEN="<access_token>"

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

curl --request POST "$DS/documentprocessing/document/convert?returnFormat=PDF" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @document.json \
  --output converted.json

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

The commands work as follows:

- `base64 -w 0` encodes the file without line breaks, and `jq -Rs .` turns the encoded text into a JSON string with quotes. Writing the body to a file keeps large documents out of 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 the PDF file.

On an unlicensed server, the endpoint answers `400` with the text "DS Server is not registered." instead of a document. [Licensing](https://docs.textcontrol.com/ds-server/administration/licensing/llms-full.txt) shows how to register the server.

### Convert a Document With .NET

The package `TXTextControl.DocumentServices.DocumentProcessing` sends the same request from C#. The following console application converts *document.docx* to PDF:

```csharp
using TXTextControl.DocumentServices.DocumentProcessing;
using TXTextControl.DocumentServices.DocumentProcessing.OAuth;

var oauthSettings = new OAuthSettings("<client ID>", "<client secret>");
var documentProcessing = new DocumentProcessing("http://localhost:5000", oauthSettings);

byte[] document = await File.ReadAllBytesAsync("document.docx");

// Convert the document and save the result
byte[] pdf = await documentProcessing.Convert(document, ReturnFormat.PDF);
await File.WriteAllBytesAsync("document.pdf", pdf);
```

The code works as follows:

- The `DocumentProcessing` constructor takes the service URL and the OAuth settings and requests an access token with the credentials of the security profile.
- `Convert` takes the document as a byte array and returns the converted document as a byte array. The package does the Base64 encoding and decoding.
- `ReturnFormat` names the target format, with the same values as the `returnFormat` parameter of the Web API.

`Convert` has three overloads: with the document only, which returns PDF, with a `ReturnFormat`, and with a `ReturnFormat` and the `flattenFormFields` value. Install the package with `dotnet add package TXTextControl.DocumentServices.DocumentProcessing`; [ASP.NET Core](https://docs.textcontrol.com/ds-server/client-libraries/aspnet-core/#documentprocessing) lists its methods.

### Choose the Target Format

Set `returnFormat` to the format your application needs:

| `returnFormat` | Creates |
|---|---|
| `PDF` | Adobe PDF |
| `PDFA` | PDF/A, the PDF format for long-term archiving |
| `DOCX` | Microsoft Word, Office Open XML |
| `DOC` | Microsoft Word 97-2003 |
| `RTF` | Rich Text Format |
| `HTML` | HTML |
| `TX` | The TX Text Control format, which the Document Editor loads and saves |
| `TXT` | Plain Unicode text |

For example, `?returnFormat=DOCX` converts an HTML page into a Word document. When DS Server runs on Linux, it supports the document formats DOCX, HTML, PDF and XLSX only, so `DOC`, `RTF`, `TX` and `TXT` are outside its documented support. [Supported File Formats](https://docs.textcontrol.com/ds-server/overview/file-formats/llms-full.txt) lists the formats per endpoint and the limits of Linux.

For a PDF with a digital signature, embedded files, passwords or access permissions, use the pdf/create endpoint instead, described in [PDF Documents](https://docs.textcontrol.com/ds-server/document-processing/pdf/llms-full.txt).

### Flatten Form Fields

A document with form fields, such as a filled-in application form, keeps its fields when it is converted. To replace every form field by its current value, add `flattenFormFields=true`:

```bash
curl --request POST "$DS/documentprocessing/document/convert?returnFormat=PDF&flattenFormFields=true" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @document.json \
  --output converted.json
```

In C#, pass the value as the third argument of `Convert`:

```csharp
byte[] pdf = await documentProcessing.Convert(document, ReturnFormat.PDF, true);
```

[PDF Form Fields](https://docs.textcontrol.com/ds-server/document-processing/pdf-forms/llms-full.txt) reads the fields of an existing PDF form.

### Convert in Other Languages

The request is plain HTTP with a JSON body, so any language that sends HTTP requests converts documents the same way: read the file, encode it as Base64, send it as a JSON string with the `Authorization` header and decode the Base64 string of the response. Keep the client secret and the token on the server; don't send these requests from code that runs in a browser.

### Next Steps

- [Merging Templates](https://docs.textcontrol.com/ds-server/document-processing/mail-merge/llms-full.txt): create documents from a template and JSON data.
- [Appending Documents](https://docs.textcontrol.com/ds-server/document-processing/appending/llms-full.txt): combine several documents into one.
- [PDF Documents](https://docs.textcontrol.com/ds-server/document-processing/pdf/llms-full.txt): create PDF and PDF/A documents with signatures and attachments.
- [Errors and Status Codes](https://docs.textcontrol.com/ds-server/document-processing/errors/llms-full.txt): what to do when a request is refused.

---

## Nearby

- **Previous:** [Authentication](https://docs.textcontrol.com/ds-server/document-processing/authentication/llms-full.txt)
- **Next:** [Merging Templates](https://docs.textcontrol.com/ds-server/document-processing/mail-merge/llms-full.txt)