# POST /v1/document/append

> Join documents with POST /v1/document/append: an AppendBody of Base64 documents with documentDivider values, DocumentSettings and a returnFormat such as PDF.

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

---

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

### Description

Combines several documents into one. The request body lists the documents, each as a Base64 string with the divider that separates it from the document before: none, a new paragraph or a new section. The response is the combined document as a Base64 string, in the format `returnFormat` names, PDF by default. See [Appending Documents](https://docs.textcontrol.com/reporting-cloud/document-processing/appending/llms-full.txt).

> Warning
>
> **Document Quota.** Each successful request counts 1 against the document quota. It counts 1 also when it combines several documents. 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 "{
        \"documents\":[
          {
              \"document\": \"UEsDBBQAAAAIAAACAAC5EQAAAAA=\",
              \"documentDivider\": 1
          },
          {
              \"document\": \"UEsDBBQAAAAIAAACAAC5EQAAAAA=\",
              \"documentDivider\": 2
          }
      ],
      \"documentSettings\":{
          \"author\": \"Text Control GmbH\",
          \"creationDate\": null,
          \"creatorApplication\": null,
          \"documentSubject\": null,
          \"documentTitle\": null,
          \"lastModificationDate\": null,
          \"userPassword\": null
      }

  }" \
  -X POST "https://api.reporting.cloud/v1/document/append?returnFormat=PDF"
```

Results:

```json
"JVBERi0xLjQNJeLjz9MNMSAwIG9iago8PAovVH..."
```

#### C#

Request:

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

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

        try
        {
            // Append the document three times, each in a new section
            byte[] bDocument = File.ReadAllBytes(documentName);

            AppendBody appendBody = new AppendBody();

            for (int i = 0; i < 3; i++)
            {
                appendBody.Documents.Add(new AppendDocument()
                {
                    Document = bDocument,
                    DocumentDivider = DocumentDivider.NewSection
                });
            }

            appendBody.DocumentSettings = new DocumentSettings()
            {
                Author = "James Henry Trotter",
                DocumentTitle = "James and the Giant Peach"
            };

            byte[] bResults = rc.AppendDocument(appendBody, ReturnFormat.PDF);

            File.WriteAllBytes("appended.pdf", bResults);
            Console.WriteLine("Appended document written to appended.pdf.");
        }
        catch (Exception e)
        {
            Console.WriteLine("An error occurred: " + e.Message);
        }
    }
}
```

Results:

```text
Appended document written to appended.pdf.
```

#### Java

Request:

```java
import com.textcontrol.reportingcloud.AppendBody;
import com.textcontrol.reportingcloud.AppendDocument;
import com.textcontrol.reportingcloud.DocumentDivider;
import com.textcontrol.reportingcloud.DocumentSettings;
import com.textcontrol.reportingcloud.ReportingCloud;
import com.textcontrol.reportingcloud.ReturnFormat;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

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

        List<AppendDocument> documents = new ArrayList<>();
        for (int i = 0; i < 3; i++) {
            documents.add(new AppendDocument(documentData, DocumentDivider.NewSection));
        }

        DocumentSettings documentSettings = new DocumentSettings();
        documentSettings.setAuthor("James Henry Trotter");
        documentSettings.setDocumentTitle("James and the Giant Peach");

        ReportingCloud r = new ReportingCloud("username", "password");
        byte[] pdfData = r.appendDocuments(new AppendBody(documents, documentSettings), ReturnFormat.PDF);

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

Results:

```text
Appended document written to appended.pdf.
```

#### Ruby

Request:

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

require "txtextcontrol/reportingcloud"
require "base64"

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

document_data = File.open(File.dirname(__FILE__) + "/test_document.docx", "rb") { |f| f.read }
document_data_b64 = Base64.strict_encode64(document_data)

documents = Array.new(3) do
  TXTextControl::ReportingCloud::AppendDocument.new(document_data_b64, :new_section)
end

document_settings = TXTextControl::ReportingCloud::DocumentSettings.new
document_settings.author = "James Henry Trotter"
document_settings.document_title = "James and the Giant Peach"

append_body = TXTextControl::ReportingCloud::AppendBody.new(documents, document_settings)
append_result = reporting_cloud.append_documents(append_body)

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

Results:

```text
Appended document written to appended.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'),
]);

$documents = [
    [
        'filename' => __DIR__ . '/test_document.docx',
        'divider'  => ReportingCloud::DOCUMENT_DIVIDER_NEW_SECTION,
    ],
    [
        'filename' => __DIR__ . '/test_document.docx',
        'divider'  => ReportingCloud::DOCUMENT_DIVIDER_NEW_SECTION,
    ],
    [
        'filename' => __DIR__ . '/test_document.docx',
        'divider'  => ReportingCloud::DOCUMENT_DIVIDER_NEW_SECTION,
    ],
];

$destinationFilename = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'test_append_document_advanced.pdf';

$documentSettings = [
    'author'                 => 'James Henry Trotter',
    'creation_date'          => time(),
    'creator_application'    => 'An awesome creator',
    'document_subject'       => 'The Old Green Grasshopper',
    'document_title'         => 'James and the Giant Peach',
    'last_modification_date' => time(),
    'user_password'          => '1',
];

$binaryData = $reportingCloud->appendDocument($documents, 'PDF', $documentSettings);

file_put_contents($destinationFilename, $binaryData);

var_dump($destinationFilename);
```

Results:

```text
string(38) "/tmp/test_append_document_advanced.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 or DOCX gets the title "ReportingCloud Test Mode" in place of the documentTitle. Not possible using the Free license. The default value is false. | yes |

### Request Payload

| Type | Value |
|---|---|
| AppendBody | The [AppendBody](#request-payload) object contains the documents encoded as Base64 strings and a ReportingCloud [DocumentSettings](#request-payload) object. |

#### AppendBody

| Name | Type | Value | Optional |
|---|---|---|---|
| documents | Array of ReportingCloud [AppendDocument](#request-payload) objects | The documents that are appended including divider options. | no |
| documentSettings | ReportingCloud [DocumentSettings](#request-payload) object | Document settings to specify document properties such as title and author. | yes |

#### AppendDocument

| Name | Type | Value | Optional |
|---|---|---|---|
| document | String | The document as a Base64 encoded string. Possible document formats are RTF, DOC, DOCX, HTML, PDF, TX, XLSX and plain text. | no |
| documentDivider | Integer | The divider between this document and the one before it, ignored for the first document. Possible values: 1 (None), 2 (NewParagraph), 3 (NewSection). Left out or given any other integer, the document is appended without a divider, as with 1. | yes |

#### DocumentSettings

| Name | Type | Value | Optional |
|---|---|---|---|
| author | String | Sets the document's author. | yes |
| creationDate | DateTime (String) | Sets the document's creation date which will be saved in the document. | yes |
| lastModificationDate | DateTime (String) | Sets the date the document is last modified. | yes |
| creatorApplication | String | Sets the application, which has created the document. | yes |
| documentSubject | String | Sets the document's subject string which will be saved in the document. | yes |
| documentTitle | String | Sets the document's title that will be saved in the document. | yes |
| userPassword | String | Specifies the password for the user to open the document. | yes |

### Success Response

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

### Error Response

| Status | Description |
|---|---|
| 400 | A 400 (Bad Request) is returned, if the request has no body, documents is left out or null, a document is left out or is not a valid Base64 string or returnFormat is not one of the possible values. An empty documents array is not an error: the response is an empty string. |
| 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 body is null, the body doesn't have the shape of an AppendBody object 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, append fewer documents, or smaller ones.

---

## Nearby

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