Verify delivery with MLS

This tutorial shows how to use Message Level Status (MLS) to confirm that a transaction was successfully handed off to the receiving access point. You'll send a transaction with MLS configured, wait for the MLS response from the receiver's Access Point, and interpret the status codes returned.

What is MLS?

Message Level Status (MLS) is the Peppol mechanism for confirming end-to-end document delivery. When you send business document in Peppol, your Access Point (C2) hands it to the receiver's Access Point (C3), which optionally hands it to the recipient's processing system (C4). MLS is the structured reply that flows back through the network telling you which of those hops succeeded.

In Arratech Connect, an MLS response surfaces on your original transaction as a Received MLS artefact, which you can fetch via the API or view in the portal.

For the protocol-level background, see the MLS section of Peppol Explained.

Prerequisites

To complete this tutorial you need:

  • An organisation, a participant, and a business document in SBD format. If you don't have these, work through Create a Participant and Send a Transaction first.
  • An Access Point. Most customers use the Shared AP that Arratech provides. Whitelabel customers operate their own AP and must have configured an MLS Receiver ID on it (covered in Step 1).
  • An API key with permission to create transactions and read artefacts.

Step 1. Confirm your AP has an MLS Receiver

Every Access Point that participates in MLS needs an MLS Receiver ID, an iso6523-actorid-upis participant identifier in the 0242: SPIS scheme. The receiver's network uses it to route MLS responses back to your AP. There are two paths depending on your setup.

When you use Arratech AP, MLS is automatically configured. The Shared AP's MLS Receiver ID is 0242:000778 and if you use a white label AP it will be extended by your seat id. You don't need to set anything yourself. Note that APs created prior to the introduction of MLS do not have an SP participant and must be recreated.

Verify yours via the API:

curl -X GET "https://api.arratech.com/access-points/{accessPointId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Look for spParticipantId in the response. In the portal, the same value appears as MLS Receiver ID on the Access Point detail view.

Step 2. Send a transaction with MLS configured

We'll send the same Peppol BIS Billing UBL Invoice as in the Send a Transaction tutorial, but with three MLS-specific decisions baked into the SBDH wrapper.

1. Choose MLS_TO — the recipient of the MLS response.

  • Shared AP — 0242:000778
  • Whitelabel AP — Your AP's own ID on form 0242:000778-xxxxxxxxxx

2. Choose MLS_TYPE — when MLS responses are returned to you.

  • ALWAYS_SEND — You receive MLS for both successful (AB/AP) and failed (RE) deliveries. Recommended for tutorials, debugging, and integrators wiring up confirmation flows.
  • FAILURE_ONLY — You receive MLS only for failures (RE). Reduces noise once you trust the happy path.

If you omit MLS_TYPE, Arratech treats it as FAILURE_ONLY (per OP-MLS-10).

3. Set a unique InstanceIdentifier — the SBDH <InstanceIdentifier> must be unique across all documents sent through Arratech Access Points within a rolling 24-hour window. Arratech uses this value to correlate the inbound MLS back to your original transaction; reusing one will cause the second send to be rejected.

Below is the SBDH-wrapped invoice. Replace the highlighted fields with your participant identifier, a fresh UID, and your chosen MLS_TO / MLS_TYPE:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<StandardBusinessDocument xmlns="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">
    <StandardBusinessDocumentHeader>
        <HeaderVersion>1.0</HeaderVersion>
        <Sender>
            <Identifier Authority="iso6523-actorid-upis">[YOUR PARTICIPANT IDENTIFIER, e.g. 0007:2120000787]</Identifier>
        </Sender>
        <Receiver>
            <Identifier Authority="iso6523-actorid-upis">[YOUR PARTICIPANT IDENTIFIER, e.g. 0007:2120000787]</Identifier>
        </Receiver>
        <DocumentIdentification>
            <Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</Standard>
            <TypeVersion>2.1</TypeVersion>
            <InstanceIdentifier>[A FRESH UID, e.g. de195274-3f0c-40ee-9f5d-83cdc898d158]</InstanceIdentifier>
            <Type>Invoice</Type>
            <CreationDateAndTime>2026-05-08T11:00:55.110+02:00</CreationDateAndTime>
        </DocumentIdentification>
        <BusinessScope>
            <Scope>
                <Type>DOCUMENTID</Type>
                <InstanceIdentifier>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::2.1</InstanceIdentifier>
                <Identifier>busdox-docid-qns</Identifier>
            </Scope>
            <Scope>
                <Type>PROCESSID</Type>
                <InstanceIdentifier>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</InstanceIdentifier>
                <Identifier>cenbii-procid-ubl</Identifier>
            </Scope>
            <Scope>
                <Type>MLS_TO</Type>
                <InstanceIdentifier>[0242:000778 for Shared AP, or your spParticipantId for Whitelabel]</InstanceIdentifier>
                <Identifier>iso6523-actorid-upis</Identifier>
            </Scope>
            <Scope>
                <Type>MLS_TYPE</Type>
                <InstanceIdentifier>ALWAYS_SEND</InstanceIdentifier>
            </Scope>
        </BusinessScope>
    </StandardBusinessDocumentHeader>
    <!-- UBL Invoice payload here — see the Send a Transaction tutorial for the body -->
</StandardBusinessDocument>

POST it to /transactions exactly as in the Send a Transaction tutorial. Note the returned transactionId, you'll use it to fetch the MLS artefact in the next step.

Step 3. Receive the MLS

The MLS response travels back through the Peppol network and surfaces on your original transaction as an artefact with itemType: MLS.

The easiest way to get notified is the mls.received webhook event. Add mls.received to a webhook's events (see Add a Webhook) and Arratech will POST a signed notification to your callback handler when the MLS arrives. The payload includes the transactionId of your original transaction, the mlsResponseCode (AP/AB/RE), and the originalInstanceId.

If you prefer polling, or need to catch up after your callback handler was unavailable, list the transaction's artefacts:

curl -X GET "https://api.arratech.com/transactions/{transactionId}/artefacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Look for an entry like:

{
  "id": "...",
  "itemType": "MLS",
  "mimeType": "application/xml",
  "createdAt": "2026-05-08T11:01:42Z"
}

In the portal, the same artefact appears as the Received MLS tile on the transaction detail view.

First you will receive either an AB or an RE MLS message. C3 can choose to also send an AP based on what kind of confirmation it can give.

  • AB → successful handover, no C4 confirmation channel available.
  • AP → successful handover, with verifiable C4 acknowledgement.
  • RE → rejection or delivery failure.

Arratech-operated APs only send AB on because they don't have a C4 confirmation callback. APs that do (e.g. with an API integration to the recipient) may also send an AP.

Timing: AB and RE typically arrive within seconds. AP may be slower since it requires C4 to actually acknowledge, there is no guaranteed SLA.

Step 4. Interpret the response code

Download the Received MLS artefact's XML body. The MLS document is a UBL ApplicationResponse. Find the <cbc:ResponseCode> element, its value tells you what happened:

  • AB Delivered toward C4 without confirmation. C3 forwarded the document (e.g. stored for pickup, emailed) but cannot verify the recipient processed it.. Successful handover, no C4 ack channel available
  • AP Delivered to C4 with confirmation. C3 has verifiable proof (API ack, file-transfer ack) that C4 received the document.. Successful handover, with C4 ack channel
  • RE Rejected or delivery toward C4 failed.. Validation failure, transport failure, or unrecoverable error

The ApplicationResponse body also carries metadata: rejection reason for RE, acknowledgement context for AB / AP. Inspect the full XML for diagnostic detail.

Reference

  • Process identifier (for the MLS document, not the original invoice): cenbii-procid-ubl::urn:peppol:edec:mls
  • Document type ID: urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:peppol:edec:mls:1.0::2.1
  • CustomizationID (inside the ApplicationResponse body): urn:peppol:edec:mls:1.0
  • ProfileID: urn:peppol:edec:mls
  • TSR reporting: MLS is reported at the SP→SP level in your Transaction Status Reports. C4 metadata may not always be available.
  • InstanceIdentifier reuse: reusing an InstanceIdentifier within 24 hours causes the second send to be rejected. Always generate a fresh UID per transaction.