> For the complete documentation index, see [llms.txt](https://dev.ropo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.ropo.com/guides/basics/other-documents.md).

# Other documents

Send letters to Ropo as **PDF + index JSON**.

Use this for customer letters, contracts, reports, and similar documents.

### Prerequisites

You need:

* `cid` + `apicode`
* a JWT token in `Authorization: Bearer <token>`

{% content-ref url="/spaces/KkTif7atlGfljOVjHocp/pages/UeD0Tz9SXbcZbDK3mwrM" %}
[Authentication](/guides/basics/authentication.md)
{% endcontent-ref %}

### Delivery options

You have two common ways to deliver the PDF.

#### Option A: HTTPS with embedded PDF (base64)

Put the base64-encoded PDF content in:

* `image.file`

Use this when your payload format supports embedded files.

#### Option B: Deliver the PDF as a separate file (ZIP)

Deliver the PDF file(s) and the index file in the **same ZIP package**.

Use this when:

* you cannot embed base64 in JSON
* the PDFs are large
* you want to upload file + data together

{% content-ref url="/spaces/KkTif7atlGfljOVjHocp/pages/klm9CwJA4jxopbWrc7DG" %}
[Data transfer limits and ZIP uploads](/guides/basics/data-transfer-limits-and-zip-uploads.md)
{% endcontent-ref %}

{% hint style="info" %}
If you use SFTP delivery, the PDF and index must still be in the same ZIP package.
{% endhint %}

### Minimum letter payload

Send one item in `datastream.dataset[]`.

```json
{
  "datastream": {
    "dataset": [
      {
        "jobtype": "301",
        "sendtype": "post",
        "customertype": "2",
        "person": "Nelli Niirulainen",
        "address": "Kellokoskenkatu 15 A 3",
        "postcode": "70100",
        "city": "KUOPIO",
        "addresscountry": "FIN",
        "countryname": "Finland",
        "propertyrow": [
          {
            "propname": "documenttype",
            "propvalue": "customerletter"
          }
        ],
        "image": {
          "filename": "letter.pdf",
          "file": "<base64-pdf>"
        }
      }
    ]
  }
}
```

{% content-ref url="/spaces/KkTif7atlGfljOVjHocp/pages/eLnfqMBfKPVmFRo55fm6" %}
[Cover page](/guides/basics/invoice/cover-page.md)
{% endcontent-ref %}

### Field reference

Fields live inside each `datastream.dataset[]` item.

#### Core fields

* `jobtype` (string, required)
  * Letter type in Ropo production.
  * For “other letter”, use `"301"`.
* `language` (string, optional)
  * Example: `"fin"`.
* `sendtype` (string, required)
  * Delivery channel.
  * Supported values:
    * `post` (printed and mailed)
    * `email`
* `customertype` (string, required)
  * `"1"` = company
  * `"2"` = consumer
* `person` (string, required if `customertype` is `"2"`)
  * Consumer recipient name.
* `company` (string, required if `customertype` is `"1"`)
  * Company recipient name.

#### Address fields

* `address` (string, required)
* `postcode` (string, required)
* `city` (string, required)
* `addresscountry` (string, required)
  * 3-letter country code (ISO 3166-1 alpha-3).
  * Example: `"FIN"`.
* `countryname` (string, required)
  * Long country name.
  * Example: `"Finland"`.

#### Email and phone

* `email` (string, required if `sendtype` is `"email"`)
* `phone` (string, optional)
  * Example: `"+35912345678"`.

#### Identifiers and dates

* `custnum` (string, optional)
  * Your customer number.
* `deliverydate` (string, optional)
  * Format: `YYYY-MM-DD`.

#### Contracts

* `contract[]` (array, optional)
  * Items contain:
    * `contract_no` (string)

#### PDF attachment (`image`)

* `image.filename` (string)
  * PDF filename.
  * Required when the PDF is delivered as a separate file with the index.
* `image.file` (string)
  * Base64-encoded PDF.
  * Optional.
  * Use this for HTTPS embedded file delivery.

#### Usage place (optional)

* `usageplaces[]` (array, optional)
  * Items can contain:
    * `address` (object)
      * `address` (string)
      * `city` (string)
      * `addresscountry` (string)
      * `postcode` (string)
      * `sitecode` (string)
    * `energycontract[]` (array)
      * `contract_no` (string)

#### Properties (`propertyrow`)

* `propertyrow[]` (array, required)
  * Use this to send the document type.
  * Each item contains:
    * `propname` (string, required)
    * `propvalue` (string, required)

### Supported `documenttype` values

Add one `propertyrow` item:

```json
{
  "propname": "documenttype",
  "propvalue": "contract"
}
```

Supported `propvalue` values:

* `invoice` (Lasku)
* `payslip` (Palkka)
* `customerletter` (Asiakaskirje)
* `questionnaire` (Kysely)
* `report` (Raportti)
* `contract` (Sopimus)
* `test` (Testi)
* `electricityinvoice` (Sähkölasku)
* `reminder` (Maksukehotus)
* `districtheatinginvoice` (Lämpölasku)
* `readingcard` (Lukemakortti)
* `adInvoice` (Ilmoituslasku)
* `interestinvoice` (Korkolasku)
* `rentinvoice` (Vuokralasku)
* `waterinvoice` (Vesilasku)
* `subscriptioninvoice` (Tilauslasku)
* `order` (Tilaus)
* `circulationinvoice` (Levikkilasku)

### Full JSON example

```json
{
  "datastream": {
    "dataset": [
      {
        "jobtype": "301",
        "language": "fin",
        "person": "Nelli Niirulainen",
        "sendtype": "email",
        "company": "Yritys Oy",
        "address": "Kellokoskenkatu 15 A 3",
        "postcode": "70100",
        "city": "KUOPIO",
        "addresscountry": "FIN",
        "countryname": "Finland",
        "email": "matti.meikalainen@mail.fi",
        "phone": "+35912345678",
        "customertype": "2",
        "contract": [
          {
            "contract_no": "EN12345678"
          }
        ],
        "image": {
          "filename": "filename.pdf",
          "file": "AFSAFAFSAF"
        },
        "usageplaces": [
          {
            "address": {
              "address": "Kuninkaankatu 15",
              "city": "KUOPIO",
              "addresscountry": "FIN",
              "postcode": "70100",
              "sitecode": "123456"
            },
            "energycontract": [
              {
                "contract_no": "123456"
              }
            ]
          }
        ],
        "deliverydate": "2017-03-03",
        "custnum": "1234RR5",
        "propertyrow": [
          {
            "propname": "documenttype",
            "propvalue": "contract"
          }
        ]
      }
    ]
  }
}
```

### Migration notes (V1 → V2)

If you still have a V1 payload, these fields were renamed in V2:

* `deliverymethod` → `sendtype`
* `countrycode` → `addresscountry`
* `country` → `countryname`
* `emailaddress` → `email`
* `phonenumber` → `phone`
* `filename` → `image.filename`
* `contractnumber` → `usageplaces.energycontract.contract_no`
* `customernumber` → `custnum`
* `deliverysite.id` → `usageplaces.address.sitecode`
* `deliverysite.address` → `usageplaces.address.address`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://dev.ropo.com/guides/basics/other-documents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.