Document Exchange

In addition to invoices, Maventa supports the exchange of other trading documents via the Peppol network. This includes ordering documents (orders, order responses, catalogues, invoice responses, reminders and more).

Exchanging structured ordering documents through Peppol automates the purchase-to-pay process. Steps like approvals, order picking, and invoicing can be handled electronically, reducing manual work and errors.

Documents endpoint

The Documents endpoint is meant for other trading documents such as orders, catalogues, despatch advice, and reminders. For exchanging invoices and credit notes, use the Invoices API.

Format conversions and full recipient lookup features are not supported for the Documents endpoint.

Document sending

Documents are sent by uploading a document file in XML format along with the required parameters in the API call.

Use POST /v1/documents to send a document. The call returns a document ID.

Parameters:

Parameter	Required	Description
`file`	Yes	The document file in XML format
`type`	No	Type of document (e.g. ORDER, CATALOGUE). If not provided, Maventa will try to determine the type from the XML content.
`recipient_eia`	No	Electronic invoicing address of the recipient
`recipient_operator`	No	Operator of the recipient (e.g. PEPPOL)
`recipient_name`	No	Name of the recipient
`recipient_country`	No	Recipient country in ISO 3166-1 alpha-2 format
`sender_eia`	No	Electronic invoicing address of the sender
`sender_name`	No	Name of the sender
`sender_country`	No	Sender country in ISO 3166-1 alpha-2 format
`transmission_id`	No	Unique transmission ID for idempotency (see Transmission ID and idempotency)
`reference_id`	No	ID of a related document to link to (requires `reference_id_type` and `type`)
`reference_id_type`	No	Type of reference: `document_id`, `external_storage_key`, or `document_file_id`

For ORDER_RESPONSE documents, additional parameters are available:

Parameter	Description
`order_response[response_code]`	ACCEPTED or REJECTED
`order_response[response_reason]`	Reason for rejection (required if rejected, max 256 characters)
`order_response[contact_name]`	Contact person name (max 64 characters)
`order_response[contact_email]`	Contact email (max 256 characters)
`order_response[contact_phone]`	Contact phone (max 32 characters)

When response_code is REJECTED, response_reason is required and at least one contact field (contact_name, contact_email, or contact_phone) must be provided.

Currently, POST /v1/documents does not perform automatic recipient lookup. To send a document, provide both the recipient’s full Peppol ID (recipient_eia) and the operator (recipient_operator set to PEPPOL) in the request parameters.

Use GET /v1/documents/{id} to check the status of a sent document, to see whether it was delivered successfully or failed. You can also use webhooks to receive real-time notifications of document status changes.

Document statuses

Documents go through the following statuses during their lifecycle:

Status	Description
`PROCESSING`	The document has been received by Maventa and is being processed for delivery.
`DELIVERED`	The document has been successfully delivered to the recipient.
`CONFIRMED_DELIVERY`	The recipient has confirmed that the document has been downloaded and processed. This status is set by the recipient using PATCH /v1/documents/{id}.
`FAILED`	The document could not be delivered. Check the document events for details about the failure.

Document receiving

To receive documents, first register the company as a document receiver using POST /v1/company/profiles.

Once registered, documents are received by listing new incoming documents in Maventa and then downloading them into the financial system:

Use GET /v1/documents with parameters direction=RECEIVED, created_at_start, and created_at_end to get a list of documents available for download. Use the per_page and page parameters for pagination.
Use GET /v1/documents/{id} to download the document.
Use PATCH /v1/documents/{id} to mark the document status to CONFIRMED_DELIVERY after downloading. Only when the document is in CONFIRMED_DELIVERY status is the download process considered completed by the system.

Only the recipient of a document can set the status to CONFIRMED_DELIVERY, and only when the document is in DELIVERED state. The API returns an error if you attempt to confirm delivery on a sent document or a document not in DELIVERED state.

Querying documents

Use GET /v1/documents to list and filter documents. The following query parameters are available:

Parameter	Description
`direction`	Filter by direction: `RECEIVED` or `SENT`
`type`	Filter by document type (e.g. ORDER, CATALOGUE)
`status`	Filter by document status
`ids`	Retrieve a batch of documents by ID (comma-separated, max 100)
`number`	Filter by document number (exact match)
`reference`	Filter by document reference (exact match)
`query`	Search across multiple fields — matches on document ID, reference, and number
`created_at_start`	Start of date range for document creation
`created_at_end`	End of date range for document creation
`sort`	Sort results by field: `id`, `type`, `status`, `number`, `reference`, `created_at`, or `received_at`. Prefix with `-` for descending order (e.g. `-created_at`). Default: `created_at` ascending.
`page`	Page number for pagination
`per_page`	Number of results per page (default: 10, max: 100)

The response includes pagination headers: X-Total, X-Total-Pages, X-Page, X-Next-Page, X-Prev-Page, X-Per-Page, and a Link header.

Transmission ID and idempotency

The transmission_id parameter in POST /v1/documents prevents duplicate document sends. If a transmission_id is provided and a document with the same value already exists, the API returns an error instead of creating a duplicate. Using transmission_id is recommended for production integrations to prevent duplicates caused by retries or network issues.

Document events

Use GET /v1/documents/{id}/events to retrieve the event history of a document. Each event contains:

Field	Description
`code`	Event code identifier
`message`	Human-readable event message
`details`	Additional information about the event
`created_at`	Timestamp of the event

Events provide an audit trail of what has happened to a document during its lifecycle — for example, delivery attempts, status changes, and errors.

In a purchase-to-pay flow, multiple document types relate to the same transaction — an order leads to an order response, then a despatch advice, and eventually an invoice. Maventa does not perform automatic order matching, but it provides tools for the integrating system to link related documents and track the full document chain.

Linking via reference parameters

When sending an ORDER_RESPONSE, you can link it to the original ORDER by providing reference_id (the document ID of the order) and reference_id_type set to document_id. This links the response to the original order in Maventa.

Example — sending an order response linked to the original order:

{
  "type": "ORDER_RESPONSE",
  "reference_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "reference_id_type": "document_id",
  "order_response": {
    "response_code": "ACCEPTED",
    "contact_name": "Jane Doe",
    "contact_email": "jane@example.com"
  }
}

Tracking documents by reference

Each document can carry a reference field (extracted from the XML content), which typically contains a purchase order number or other business reference. Use this field to correlate documents across the transaction lifecycle:

Filter documents by reference: GET /v1/documents?reference=PO-2025-001
Search across ID, reference, and number: GET /v1/documents?query=PO-2025-001

For example, if an order, despatch advice, and invoice all carry the same purchase order reference, you can retrieve all related documents with a single query. The integrating system can then perform its own matching logic — such as three-way matching between order, goods receipt, and invoice.

Registering for document types

To receive ordering and other document types, register the company for each desired profile using POST /v1/company/profiles. Specify the profile name, network, and profile version.

Example request:

{
  "network": "PEPPOL",
  "profiles": ["INVOICE_RESPONSE"],
  "profile_version": "PEPPOLBIS30"
}

Ordering profiles (ORDER, ORDER_RESPONSE, CATALOGUE, CATALOGUE_RESPONSE, DESPATCH_ADVICE, and REMINDER) require a profile version — either PEPPOLBIS30 or EHF30. Registration without a profile version will fail. Make sure the integrating system is able to process the requested profile version.

Supported profiles and versions

ORDER

The buyer sends an Order to a supplier to request goods or services. The order contains details such as item descriptions, quantities, prices, delivery dates and delivery addresses. It serves as the formal starting point of a purchase transaction in the Peppol procurement flow.

Profile versions: PEPPOLBIS30, EHF30

Markets: FI, NO, SE, DK, NL

Peppol document identifiers:

PEPPOLBIS30: urn:oasis:names:specification:ubl:schema:xsd:Order-2::Order##urn:fdc:peppol.eu:poacc:trns:order:3::2.1
EHF30: urn:oasis:names:specification:ubl:schema:xsd:Order-2::Order##urn:fdc:peppol.eu:poacc:trns:order:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2

ORDER_RESPONSE

The supplier sends an Order Response back to the buyer after receiving an order. The response indicates whether the order is accepted, rejected, or accepted with changes — for example, adjusted quantities or delivery dates. This closes the loop on the ordering process before fulfilment begins.

Profile versions: PEPPOLBIS30, EHF30

Markets: FI, NO, SE, DK, NL

Peppol document identifiers:

PEPPOLBIS30: urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2::OrderResponse##urn:fdc:peppol.eu:poacc:trns:order_response:3::2.1
EHF30: urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2::OrderResponse##urn:fdc:peppol.eu:poacc:trns:order_response:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2

CATALOGUE

A supplier sends a Catalogue to a buyer to present the available products or services, including item details, pricing, and classification. Catalogues form the basis for structured ordering — the buyer can reference catalogue items directly when placing orders, reducing manual entry and errors.

Profile versions: PEPPOLBIS30, EHF30

Markets: FI, NO, SE, DK, NL

Peppol document identifiers:

PEPPOLBIS30: urn:oasis:names:specification:ubl:schema:xsd:Catalogue-2::Catalogue##urn:fdc:peppol.eu:poacc:trns:catalogue:3::2.1
EHF30: urn:oasis:names:specification:ubl:schema:xsd:Catalogue-2::Catalogue##urn:fdc:peppol.eu:poacc:trns:catalogue:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2

CATALOGUE_RESPONSE

The buyer sends a Catalogue Response back to the supplier to confirm whether a received catalogue has been accepted or rejected. This allows the supplier to know if their catalogue is active and available for ordering on the buyer’s side.

Profile versions: PEPPOLBIS30, EHF30

Markets: FI, NO, SE, DK, NL

Peppol document identifiers:

PEPPOLBIS30: urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:catalogue_response:3::2.1
EHF30: urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:catalogue_response:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2

DESPATCH_ADVICE

The supplier sends a Despatch Advice to the buyer when goods are shipped. It lists what was actually sent — item descriptions, quantities, batch numbers, and packaging details. The buyer can use it to prepare for goods reception and match the shipment against the original order before the invoice arrives.

Profile versions: PEPPOLBIS30, EHF30

Markets: FI, NO, SE, DK, NL

Peppol document identifiers:

PEPPOLBIS30: urn:oasis:names:specification:ubl:schema:xsd:DespatchAdvice-2::DespatchAdvice##urn:fdc:peppol.eu:poacc:trns:despatch_advice:3::2.1
EHF30: urn:oasis:names:specification:ubl:schema:xsd:DespatchAdvice-2::DespatchAdvice##urn:fdc:peppol.eu:poacc:trns:despatch_advice:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2

VOUCHER

A Voucher is a financial document typically used in the public sector to authorise or record a payment, such as expense claims, internal transfers, or other non-invoice payment authorisations. In Maventa, VOUCHER is supported on the scanning network (VISMASCANNER) — there is no Peppol document identifier for this type. Read more about scanning.

Network: VISMASCANNER

Markets: FI, NO, SE, DK, NL

SELF_BILLING_INVOICE

A Self-Billing Invoice is created by the buyer instead of the supplier. In a self-billing arrangement, the buyer calculates the amount owed and issues the invoice on behalf of the supplier. This is common in industries with frequent deliveries or consignment stock, where the buyer has better visibility into what was received. Self-billing is supported via the invoices endpoint. Read more about self-billing support.

Profile versions: PEPPOLBIS30

Peppol document identifier:

urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1

SELF_BILLING_CREDIT_NOTE

A Self-Billing Credit Note follows the same principle as a Self-Billing Invoice — it is issued by the buyer on behalf of the supplier. It is used to correct or reverse a previously issued self-billing invoice, for example when goods are returned or an amount was calculated incorrectly. Self-billing is supported via the invoices endpoint. Read more about self-billing support.

Profile versions: PEPPOLBIS30

Peppol document identifier:

urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1

RECEIPT

A Receipt Advice is sent by the buyer to the supplier to confirm that goods or services have been received. It can report full or partial receipt, and may include details about rejected or damaged items. The supplier can use this as confirmation before invoicing.

Profile versions: PEPPOLBIS30

REMINDER

A Reminder is a payment reminder sent to a buyer when an invoice is overdue. This is a Norwegian-specific profile based on the EHF Reminder specification. Technically, it reuses the Invoice document type with a reminder-specific conformance identifier, which means the XML structure follows the invoice format but is identified as a reminder through the customisation ID.

Profile versions: PEPPOLBIS30, EHF30

Markets: FI, NO, SE, DK, NL

Peppol document identifier:

urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0#conformant#urn:fdc:anskaffelser.no:2019:ehf:reminder:3.0::2.2

INVOICE_RESPONSE

The buyer sends an Invoice Response to communicate the processing status of a received invoice back to the supplier. The response can indicate that the invoice has been received, is under processing, has been approved, rejected, or is conditionally accepted. This gives suppliers visibility into where their invoice stands in the buyer’s approval workflow.

Profile versions: PEPPOLBIS30

Markets: FI, NO, SE, DK, NL, BE

Peppol document identifier:

urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1

MESSAGE_LEVEL_RESPONSE

A Message Level Response (MLR) is an automated technical acknowledgement sent by the receiving access point or end system. Unlike the Invoice Response, which reflects a business decision, the MLR indicates whether the document was successfully received and could be processed at a technical level — for example, whether the XML was valid and the recipient could be identified. It is part of the Peppol infrastructure layer rather than the business document flow.

Profile versions: PEPPOLBIS30

Markets: FI, NO, SE, DK, NL, BE

Peppol document identifier:

urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1

INVOICE Deprecated

Use INVOICE_AND_CREDIT_NOTE instead. Invoices and credit notes are handled via the Invoices API, not the Documents endpoint. Read more about invoice sending.

CREDIT_NOTE Deprecated

Use INVOICE_AND_CREDIT_NOTE instead. Invoices and credit notes are handled via the Invoices API, not the Documents endpoint. Read more about invoice sending.

ORDER_CHANGE Removed

Order change documents are defined in the Peppol advanced ordering specification but are not currently fully supported by Maventa. If you are interested in this document type, please contact Maventa support.

ORDER_CANCELLATION Removed

Order cancellation documents are defined in the Peppol advanced ordering specification but are not currently fully supported by Maventa. If you are interested in this document type, please contact Maventa support.

EXPRESSION_OF_INTEREST_REQUEST Removed

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.

EXPRESSION_OF_INTEREST_RESPONSE Removed

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.

TENDER_STATUS_REQUEST Removed

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.

CALL_FOR_TENDERS Removed

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.

TENDER Removed

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.

TENDER_RECEIPT Removed

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.

BANK_FILE Removed

Not currently fully supported by Maventa. If you are interested in this document type, please contact Maventa support.

SCAN Removed

Scanning is handled through a separate scanning service and the profiles API, not the Documents endpoint. Read more about scanning.

If you are interested in a document type not listed here, please contact Maventa support.

Document Exchange

Documents endpoint

Document sending

Document statuses

Document receiving

Querying documents

Transmission ID and idempotency

Document events

Registering for document types

Supported profiles and versions

AI Chat Support 24/7

Got feedback?

Document Exchange

Documents endpoint

Document sending

Document statuses

Document receiving

Querying documents

Transmission ID and idempotency

Document events

Linking related documents

Registering for document types

Supported profiles and versions

AI Chat Support 24/7

Got feedback?