# 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>"
        }
      }
    ]
  }
}
```

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

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

The question should be specific, self-contained, and written in natural language.
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.