# POST /v1/document/convert

> Send a Base64 document in RTF, DOC, DOCX, HTML, PDF, TX, XLSX or plain text and get it back as PDF, PDFA, DOCX, DOC, RTF, HTML, TXT or TX, set by returnFormat.

- **Product:** ReportingCloud
- **Section:** Documentation
- **Kind:** Endpoint
- **Path:** ReportingCloud > API Reference > Web API > Document > /convert > POST /v1/document/convert
- **3090 words**
- **Web URL:** https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/convert/post/
- **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/convert/post/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/convert/post/llms-full.txt

---

`POST` `https://api.reporting.cloud/v1/document/convert`

### Description

Converts a document to another format. The request body is the document as a Base64 string: the service recognizes DOCX, DOC, RTF, HTML, PDF, TX and XLSX by their content and reads anything else as plain text. `returnFormat` names the format to create, PDF by default, and the response is the converted document as a Base64 string. See [Converting Documents](https://docs.textcontrol.com/reporting-cloud/document-processing/converting/llms-full.txt).

> Warning
>
> **Document Quota.** Each successful request counts 1 against the document quota. A test run (`test=true`) doesn't count. [Plans and Licensing](https://docs.textcontrol.com/reporting-cloud/overview/licensing/llms-full.txt) lists the quota of each plan.

### Examples

#### HTTP

Request:

```bash
curl -u username:password \
  -H "Content-Type: application/json" \
  --data \
  " \
  \"CAcBAA4AAAAAAAAAAAAAAAIAAABsAQAAAQ...==\"" \
  -X POST "https://api.reporting.cloud/v1/document/convert?returnFormat=RTF"
```

Results:

```json
"e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcdWMxXGRlZmYwXGFkZWZmMFxkZWZsYW5n..."
```

#### C#

Request:

```csharp
using System;
using System.Collections.Generic;
using System.Drawing;
using System.IO;
using TXTextControl.ReportingCloud;

class RCSamples
{
    public static void ConvertDocument(string templateName)
    {
        ReportingCloud rc = new ReportingCloud(
            "username",
            "password",
            new Uri("https://api.reporting.cloud"));

        try
        {
            // Read the document and convert it to DOCX
            byte[] bDocument = File.ReadAllBytes(templateName);
            byte[] bResults = rc.ConvertDocument(bDocument, ReturnFormat.DOCX);

            File.WriteAllBytes("results.docx", bResults);
            Console.WriteLine(templateName + " has been converted to DOCX.");
        }
        catch (Exception e)
        {
            Console.WriteLine("An error occurred: " + e.Message);
        }
    }
}
```

Results:

```text
test.tx has been converted to DOCX.
```

#### Java

Request:

```java
import com.textcontrol.reportingcloud.ReportingCloud;
import com.textcontrol.reportingcloud.ReturnFormat;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class ReportingCloudSample {
    public static void main(String[] args) throws IOException {
        byte[] documentData = Files.readAllBytes(Paths.get("template.tx"));

        ReportingCloud r = new ReportingCloud("username", "password");
        byte[] pdfData = r.convertDocument(documentData, ReturnFormat.PDF);

        String pdfFileName = "converted.pdf";
        Files.write(Paths.get(pdfFileName), pdfData);
        System.out.println("Converted document written to " + pdfFileName + ".");
    }
}
```

Results:

```text
Converted document written to converted.pdf.
```

#### Ruby

Request:

```ruby
#!/usr/bin/env ruby

require "txtextcontrol/reportingcloud"
require "base64"

reporting_cloud = TXTextControl::ReportingCloud::ReportingCloud.new("username", "password")

template_data = File.open(File.dirname(__FILE__) + "/sample_invoice.tx", "rb") { |f| f.read }
template_data_b64 = Base64.strict_encode64(template_data)

convert_result = reporting_cloud.convert_document(template_data_b64)

pdf_file_name = "converted.pdf"
File.open(File.dirname(__FILE__) + "/#{pdf_file_name}", 'wb') do |f|
  f.write(Base64.strict_decode64(convert_result))
end
puts "Converted document written to #{pdf_file_name}."
```

Results:

```text
Converted document written to converted.pdf.
```

#### PHP

Request:

```php
<?php

require_once __DIR__ . '/vendor/autoload.php';

use TextControl\ReportingCloud\ReportingCloud;

$reportingCloud = new ReportingCloud([
    'api_key' => (string) getenv('REPORTINGCLOUD_API_KEY'),
]);

$sourceFilename      = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'sample_invoice.tx';
$destinationFilename = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'sample_invoice.pdf';

$binaryData = $reportingCloud->convertDocument($sourceFilename, 'PDF');

file_put_contents($destinationFilename, $binaryData);

var_dump("Written converted document to {$destinationFilename}");
```

Results:

```text
string(53) "Written converted document to /tmp/sample_invoice.pdf"
```

### Authorization

This endpoint requires a "ReportingCloud-APIKey" or a "Basic" user authorization to access the user account, data and templates. Only one of these two methods is required.

[API Keys](https://docs.textcontrol.com/reporting-cloud/installation/api-keys/llms-full.txt) describes how to create an API key, and [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt) explains both header forms.

#### ReportingCloud-APIKey

| Header field | Description |
|---|---|
| Authorization | **Required**. A valid ReportingCloud account is required. The Authorization field is constructed as follows: An API key needs to be generated in the portal or with [PUT /v1/account/apikey](https://docs.textcontrol.com/reporting-cloud/reference/web-api/account/apikey/put/llms-full.txt). The authorization method and a space, "ReportingCloud-APIKey ", is then put before the actual API key string. For example: `Authorization: ReportingCloud-APIKey oMDM4MrAqL9QEOpyzupnQW5NjvCNtvE5cVDaaLqxI` |

#### Basic

| Header field | Description |
|---|---|
| Authorization | **Required**. A valid ReportingCloud account is required. The Authorization field is constructed as follows: The user name and password are combined into a string separated by a colon, for example `username:password`. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. The authorization method and a space, "Basic ", is then put before the encoded string. For example: `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l` |

### Request Parameters

| Name | Type | Value | Optional |
|---|---|---|---|
| returnFormat | String | A string that specifies the format of the created document. Possible values are: PDF, PDFA, RTF, DOC, DOCX, HTML, TXT and TX, in any letter case. The default value is PDF. PDFA requires an Extreme license. | yes |
| test | Boolean | Specifies whether it is a test run or not. A test run is not counted against the quota, and the created document contains a "TEST MODE" watermark. A PDF gets the title "ReportingCloud Test Mode". Not possible using the Free license. The default value is false. | yes |

### Request Payload

| Type | Value |
|---|---|
| Base64 encoded string | The source document encoded as a Base64 string, sent as a JSON string. Possible document formats are .rtf, .doc, .docx, .html, .pdf, .tx, .xlsx and plain text. Data in another format is read as plain text. |

### Success Response

| Status | Description |
|---|---|
| 200 | On success, the HTTP status code in the response header is 200 (OK). The response body contains the converted document encoded as a Base64 encoded string. |

### Error Response

| Status | Description |
|---|---|
| 400 | A 400 (Bad Request) is returned, if no data is found in the request body, the body is not a JSON string or returnFormat is not one of the possible values. |
| 403 | A 403 (Forbidden) is returned, if the user is not authorized, the document quota is exceeded or the return format PDFA is requested without an Extreme license. |
| 405 | A 405 (Method Not Allowed) is returned, if the request uses another HTTP method than POST. The Allow header of the response names POST. |
| 411 | A 411 (Length Required) is returned, if the request has neither a body nor a Content-Length header. |
| 415 | A 415 (Unsupported Media Type) is returned, if the request has a body but no Content-Type header, or a Content-Type such as text/plain that the endpoint doesn't read. Send Content-Type: application/json. |
| 500 | A 500 (Internal Server Error) is returned, if the request has no Authorization header, an empty one or one that is not the authorization method, a space and the credentials, or if the request body is not a valid Base64 string or returnFormat is empty. |

**Timeout Limitation.** The pure processing time is limited to a maximum of **60 seconds**. After this period of time, the task is canceled.

A typical document should not take more than 5 seconds. If your request takes longer, reduce the size of the document.

---

## Nearby

- **Previous:** [/v1/document/convert](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/convert/llms-full.txt)
- **Next:** [/v1/document/findandreplace](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/findandreplace/llms-full.txt)