Mass Printing Service

The Maventa Mass Printing Service, also referred to as Payslip, allows sending PDF files as physical letters through the Finnish printing service. While originally designed for distributing payslips, it can be used for sending any type of letters, provided the printing service rules are followed. This service is available only for Finnish companies.

User account opening

To use the Mass printing API, you need a dedicated user account. Create one by calling the registration endpoint with your existing sw_api_key and company_uuid from Maventa:

• Production: https://payslip.maventa.com/register
• Staging: https://payslip-stage.maventa.com/register

Request for registering

Response for registering

The response code will always be a HTTP 200 and the response body is one of the following:

Sending letters

To send a letter to Mass printing service there are currently two supported methods:

1. New JSON-based API (recommended) - https://payslip.maventa.com/input_json
2. Legacy IPOSTXML-based method (deprecated - will be removed in future) - https://payslip.maventa.com/input_public

JSON API (recommended)

The POST /input_json endpoint allows authenticated users to send PDF files for print delivery services. This endpoint accepts multipart form data containing a PDF file and associated metadata for both recipient and sender information.

Authentication for JSON API

The endpoint supports multiple authentication methods for backwards compatibility:

Method 1: Bearer token authentication (recommended). Note! This is not using the common OAuth that our other services, it is the static user API key

Header Required:

• Authorization: Bearer {user_api_key}
• X-Client-Id: company_uuid

Method 2: Legacy API key authentication (deprecated)

Headers Required:

• USER_API_KEY: user_api_key
• COMPANY_UUID: company_uuid

Method 3: Legacy username/password authentication (deprecated)

Headers Required:

• USERNAME: Your username
• USERPW: Your password

Sending with JSON API

• Method: POST
• Content-type: multipart/form-data
• URL: /input_json

Required parameters

Recipient information (required)

Optional parameters

Optional sender information (required for digital post send)

Optional recipient information (used for digital post lookups for better matching)

Printing options

Licensing parameters

Response codes and values for sending

Success response for sending

• Status code: 201 Created
• Body: UUIDof newly created printable letter

Error responses for sending

Example requests for sending

Using Bearer Token Authentication (Recommended)

curl -X POST "https://payslip-stage.maventa.com/input_json" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "X-Client-Id: your_company_uuid_here" \
  -F "pdf=@document.pdf" \
  -F "hash=a1b2c3d4e5f6789..." \
  -F "version=MyERP 1.25" \
  -F "sw_api_key=your_sw_api_key_here" \
  -F "recipient[name]=Essi Esimerkki" \
  -F "recipient[address]=Kotikatu 123" \
  -F "recipient[post_code]=00100" \
  -F "recipient[post_office]=Helsinki" \
  -F "recipient[country]=FI" \
  -F "sender[name]=Tulostaja Oy Ab" \
  -F "sender[sender_id]=00371234567890" \
  -F "duplex=true" \
  -F "color_print=false" \
  -F "letter_class=economy"

GET /file_status/:id API Endpoint

The /file_status/:id endpoint allows authenticated users to check the processing status of a specific payslip using its UUID. The endpoint supports the same authentication methods as the /input_json endpoint described above.

• Method: GET
• URL: /file_status/{payslip_uuid}

Response codes and values for status call

Success response for status call

• Status code: 200 OK
• Body: Status string indicating current processing state

Possible status values for status call

Error response for status call

Example requests for status call

curl -X GET "https://payslip-stage.maventa.com/file_status/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Client-Id: your_company_uuid_here"

GET /file_status/:id/details API Endpoint

The /file_status/:id/details endpoint returns the same overall status as /file_status/:id, but adds a per-letter breakdown including the delivery method actually used. This is the way to find out whether a letter was delivered to the recipient’s digital mailbox or printed and posted. The endpoint supports the same authentication methods as the endpoints described above.

• Method: GET
• URL: /file_status/{payslip_uuid}/details

Success response for detailed status call

• Status code: 200 OK
• Content-type: application/json

{
  "status": "DONE",
  "letters": [
    { "filename": "letter_1.pdf", "status": "delivered", "delivery_method": "omaposti" },
    { "filename": "letter_2.pdf", "status": "delivered", "delivery_method": "print" }
  ]
}

Error response for detailed status call

Example request for detailed status call

curl -X GET "https://payslip-stage.maventa.com/file_status/550e8400-e29b-41d4-a716-446655440000/details" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Client-Id: your_company_uuid_here"

IPOSTXML-based API (deprecated)

Authentication for IPOSTXML-based API

The endpoint supports multiple authentication methods for backwards compatibility:

Method 1: Bearer token authentication (recommended). Note! This is not using the common OAuth that our other services, it is the static user API key

Header Required:

• Authorization: Bearer {user_api_key}
• X-Client-Id: company_uuid

Method 2: Legacy API key authentication (deprecated)

Headers Required:

• USER_API_KEY: user_api_key
• COMPANY_UUID: company_uuid

Method 3: Legacy username/password authentication (deprecated)

Headers Required:

• USERNAME: Your username
• USERPW: Your password

POST parameters for IPOSTXML-based API

Response for sending with IPOSTXML-based API

The response code will be a HTTP 200 and the response body is one of the following or “401 Unauthorized” if authentication fails:

Zip file content

PDFs

• One zip file can contain multiple PDF files but only one letter per PDF file. One letter can have multiple pages.
• Each PDF must be accompanied with iPost-XML metadata file (iPost LetterBundle format version 0.4). Note! information given in IPost-XML overrides the API parameters. You can download a zip file containing iPost-XML v0.4 implementation guidelines
• One iPost-XML should only have reference to one PDF letter (iPost-XML to PDF 1-1 ratio)
• Page count on the iPost-XML (pages element) must match to the actual page count of the PDF
• We prefer that one zip file contains only one letter (one PDF file) + iPost-XML metadata file
• When multiple IPost-XMLs in one ZIP file, all IPost-XMLs must have the same printing options (letter class, colour..)
• Always use unique hash for each zip file. zipHash and hash values can be the same since one ZIP file can contain multiple PDF files
• Zip file max size is 1 GB

<?xml version="1.0" encoding="ISO-8859-1"?>
<lb:LetterBundle schemaVersion="v0x4" senderFileId="FileD1" xmlns:lb="urn:itella-letterbundle-v0x4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:itella-letterbundle-v0x4 LetterBundle_V0x4.xsd">
  <lb:Bundle senderBundleId="">
    <lb:BundleCommon creationDate="2020-06-24T13:17:00.0Z" isTest="false">
      <lb:Sender companyName="Your company Oy" contact="" contactPerson="Support" email="support@support.com" phoneNumber="010-5058474" ovtID="003712345678">
        <lb:SenderAddress>
          <lb:Eu1 name="Your company Oy" address="PL 000" postalCode="00101" city="Helsinki" countryCode="FI"/>
        </lb:SenderAddress>
      </lb:Sender>
      <lb:StdBundleProcessing customerId="" departmentClassification="false" electronicArchiving="T" envelope="S" fileFormat="0" isDuplex="true" letterClass="2" paper="0" password="" serviceFunction="0"/>
      <lb:ExternalFile fileName="sent_filename.pdf" format="PDF" senderFileId="wm_0c5c09e0-03d3-4340-bb6b-0c3c14be7f42">
        <lb:CheckSum type="MD5" value="nnnnnnnnnnnnn"/>
      </lb:ExternalFile>
    </lb:BundleCommon>
    <lb:Letter senderLetterId="LetterID1">
      <lb:LetterMeta>
        <lb:Location pages="1" startPage="1"/>
        <lb:Recipient>
          <lb:Address>
            <lb:Eu1 address="Kotikatu 1" city="Helsinki" countryCode="FI" name="Asiakas Anssi" postalCode="01001"/>
          </lb:Address>
        </lb:Recipient>
      </lb:LetterMeta>
    </lb:Letter>
  </lb:Bundle>
</lb:LetterBundle>

Checking the status of sent packages for IPOSTXML-based API

To check the status of the sent package, use https://payslip.maventa.com/file_status.

Headers for checking the file status

You need to give authentication using HTTP headers. You can give either:

• USERNAME and USERPW with which you registered your Mass printing API account
• COMPANY-UUID and USER-API-KEY of your Maventa account

GET parameter for checking the file status

Response for checking the file status

Technical restrictions of the PDF

All files must be of PDF format (or have the same content requirements) for it to be printed correctly. That means that the file cannot contain dynamic components and that all fonts, images and others are included in the file (ie the files should be 100% “self-contained”). All new customers must test their PDF files (all variants of fonts, images, etc.) to verify that the PDFs can be handled. If the PDF contains graphics, such as logos, charts, and other images, they must be of good quality.

• Keep the top and right margins empty
• Do not send any invoice image or attachment with black/dark background
• No transparencies
• All fonts must be embedded (subset or complete)
• All images must be in 250-300dpi. Higher resolution produces little or no quality gain. Lower resolution gives poor quality.
• Text should be stored as text (not bitmap)
• Recommended size per page is 1024kB, smaller the better
• Black / White print: 2-bit colours (black and white only), not grayscale.
• Colour print: Black text should be in black, not 4-colour
• Colour print: All colours must be CMYK
• PDF page size needs to be A4 (210 x 297 millimeters)

Instructions for letter layout

Your PDF letter needs to follow these PDF layout rules by Posti. Addition to Posti as the mail distributor, there is also Jakeluyhtiö Suomi Oy (JYS) which have few additions to the Posti rules. Difference is the tracking barcodes they print on the invoice image, see the JYS rules merged with the Posti ones.

Receiver information should be marked as clearly as possible to make sure machine readability.

Envelope size

The Finnish printing service uses two envelope sizes:

• For letters of up to 9 sheets, a smaller C5 envelope is used.
• For letters exceeding 9 sheets, a larger and more expensive C4 envelope is used.

The limit counts sheets of paper, not PDF pages. With duplex printing two pages fit on one sheet, so a duplex letter of up to 18 pages still fits a C5 envelope.

Storage time

Once Maventa receives final confirmation from the print service provider, the sent file itself is completely removed from Maventa’s servers. We recommend storing the files on the ERP side for at least a few months after the sending in case there are some support cases related to the sent letters.

What remains after the file has been removed:

• Batch details — filename, letter count, letter class, status and timestamps — stay available in the file listing and through the status endpoints, so sendings can still be traced.
• Recipient details given in the API call are cleared 90 days after the letter was created.
• A social security number given for a digital post lookup is cleared as soon as the letter reaches its final status, whether it was delivered or ended in an error.

Delivery schedule

Letters that are sent to Maventa before 24:00 will get printed, processed and enveloped overnight and handed over to the mail distributor the following morning. Production does not take place during the weekends and holidays.

Delivery depends on the selected letter class. For Finnish companies sending domestic letters, there are two options: Priority and Economy.

For Finnish domestic letters, the practical difference between Priority and Economy is often minimal. Regional delivery schedules can have more impact on delivery timing than the letter class itself. Priority may still benefit B2B invoicing, but for consumer invoices, the recipient’s local delivery schedule is usually the deciding factor.

For international letters, only priority is available.

Digital post delivery

Digital post means delivering a letter to the recipient’s digital mailbox instead of printing and posting it. When a recipient has a digital mailbox account, they have actively opted in to digital delivery. Digital delivery is faster and cheaper than a paper letter, and it reaches recipients in the channel they have chosen.

Two lookup points

From 15th of October 2026, a letter can be identified as digital post at two points in the flow. Both end up in the recipient’s OmaPosti, but they differ in what they require, what the sender gets to see, and what the letter costs.

On 1st of March 2027, the print service provider’s separate lookup is removed and all OmaPosti lookups are performed by Maventa. That leaves one digital post channel, which is reported to the sender and priced as a digital delivery.

Traffic is not moved to Maventa’s lookup automatically. A letter takes that route only when it carries recipient details, which means sending it with the JSON API (POST /input_json) or with the IPOSTXML-based method where the recipient is given in the iPost-XML metadata.

Requirements for Maventa’s digital post lookup

Digital post delivery through Maventa’s own lookup is attempted only when all of the following are true. If any of them is not met, the letter continues to the print route as normal, where the print service provider’s lookup may still deliver it digitally, though without reporting it back and at the printed letter price.

• The letter carries recipient details. These are only available when sending with the JSON API, or with the IPOSTXML-based method where the recipient is given in the iPost-XML metadata. Letters sent as plain PDFs in a ZIP package (document_type=PDF), including everything sent through the mass printing user interface, carry no recipient details and are therefore never matched by Maventa’s lookup.
• The recipient is in Finland. The recipient’s country must be FI or left empty.
• prevent_digital_post is not set. Setting it to true opts the letter out of digital post entirely, at both lookup points.
• The PDF is at most 10 MB. Larger letters fall through to the print route automatically.

How Maventa’s lookup works

Before a letter is handed over to the print service provider, Maventa performs an automatic lookup against the digital mailbox registry using the recipient’s information. If a match is found, the letter is delivered to the recipient’s digital mailbox instead of being printed and mailed. If no match is found, delivery falls through to the normal print route.

The lookup is performed using the following recipient data, in priority order:

1. Social security number (SSN)
2. Email address
3. Full name + street address + postal code + post office
4. Full name + phone number

Maventa’s lookup does not require the sender’s OVT code. The sender account (tenant) is based on the company’s business ID (BID), so no OVT information needs to be included in the API call. The print service provider’s lookup does require the sender’s OVT code, along with the recipient’s name and address.

Automatic sender setup

Each company can have only one sender account (tenant) in the digital mailbox service. The tenant represents the company as a recognised sender, and its name is what recipients see in their inbox.

If a tenant does not already exist for the company, Maventa automatically creates one when the company’s first letter is delivered as digital post. No action is required. Maventa sets the tenant name based on the company’s official name from the YTJ registry at the time the company was created in Maventa.

If another service provider has already created a tenant for the company, that existing tenant and its name are used. To update the tenant name, contact the digital mailbox provider directly.

Custom letter subject

You can customise the letter subject that the recipient sees in their digital mailbox using the letter_subject parameter. By default, the subject is “Kirje lähettäjältä [company name]”.

Opting out of digital post delivery

To force physical delivery for a specific letter, for example when a guaranteed paper trail is required, set the prevent_digital_post parameter to true in the API call. This opts the letter out of digital post at both lookup points.

Billing

Digital post deliveries made through Maventa’s own lookup are billed as consumer invoices. The billing action is EINVOICE_KIVRA_FI until 15th of October 2026 and EINVOICE_OMAPOSTI_FI after that. The price does not change.

Letters delivered through the print service provider’s lookup are billed as printed letters, which is considerably more expensive. Moving traffic to Maventa’s lookup makes delivery information and pricing consistent, because a digital delivery is then always identified at the same point in the flow.

User account closing

If you wish to close the service, please contact Maventa support.