Procurement Service Bus

# Peppol v1

The Peppol endpoints are used to look for recipients in Peppol, or to edit your Peppol configurations. To learn more about Peppol visit "What is Peppol".

Search for Peppol participants using this simple discovery tool.

Search for a partyId that uses a scheme from the Peppol Participant Schemes list.

# Delivery options

The peppol/deliveryOption endpoint offers advanced options when looking for recipients in OpenPeppol. The queryRecipientParty endpoint should be efficient enough for most users. But if you are an advanced user, you could use this endpoint.

When sending documents it is good to know the partyId that will guarantee the best delivery. The peppol/deliveryOption endpoint lets you request the best partyId to use with the salesInvoice/send endpoint. An organisation can have more than one partyId registered in the SMP to receive documents. The deliveryOption API will return the partyId that best fits the sending request.

To call the deliveryOptions API use the GET /api/v1/peppol/deliveryOption endpoint. Use these parameters to limit the returned values:

Name Type Description
partyIds array[string] (query) All possible partyIds of the recipient party.
preferredDocumentTypeId srting (query) The source or preferred documentTypeId to match with and to determine the partyId format.
documentTypeIds array[string] (query) Filter on document formats.
documentFamily string (query) Filter on a family.
isCredit boolean (query) Example: Set it to true, to search only for CreditNotes or to false if you don’t want to include CreditNotes in our result set.

Example: GET https://accp-psb.econnect.eu/api/v1/peppol/deliveryOption?partyIds=0106%3A54441587&partyIds=9944%3ANL12345678B01&documentFamily=Invoice

This will give a response containing a list of data to be used for sending, sorted on best value first. If there is no match the response will be empty.

# Returned elements

Name Type Description
partyId string
documentTypeId string The document format type id
processId string
protocol string AS2, AS4. (Enum: Array 2 )
url string Ap url
certificate string AP cert (Only valid OpenPeppol PKI)

# Response example

[
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:www.cenbii.eu:transaction:biitrns071:ver2.0:extended:urn:www.peppol.eu:bis:peppol36a:ver1.0::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii36:ver2.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF .... AT00kF4Xw=="
    },
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.simplerinvoicing.org:si:si-ubl:ver1.2::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii04:ver1.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF0 ... GItkAT00kF4Xw=="
    },
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.simplerinvoicing.org:si:si-ubl:ver1.2::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii04:ver2.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF0 ... GItkAT00kF4Xw=="
    },
    {
        "partyId":"0106:54441587",
        "documentTypeId":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0::2.1",
        "processId":"urn:www.cenbii.eu:profile:bii04:ver2.0",
        "protocol":"As4",
        "url":"https://accp-ap.econnect.eu/as4/v1",
        "certificate":"MIIF0z ... GItkAT00kF4Xw=="
    }
]

# Peppol registration

Users with the ApManager role can use the Peppol endpoints to manage their parties in the eConnect SMP and Peppol SML. When adding new parties to the Peppol network, please make sure these parties are assigned to users who have sending and/or receiving capabilities and make sure there are hooks registered for the partyId. To do this all in one go, you can use the Enrollment endpoint.

# Register in Peppol

ApManagers can register a party in Peppol by calling the PUT method on the /api/v1/peppol/config/party/{partyId} endpoint. The given partyId is registered in the PEPPOL SML and in the eConnect SMP, using the configuration provided in the payload. Using the PUT method in combination with a partyId that is already registered will update the registration and configuration. Calling the GET method on the same endpoint will show you the current Peppol configuration for the provided partyId. Invoking the GET method on endpoint api/v1/peppol/config/party shows you all parties that are already registered in the eConnect SMP for your organization.

# Verification

The Peppol service configuration object includes verification, businessCard and capabilities. Verification is used to prove you are in compliance with the 'Know Your Customer policy' of the 'Peppol compliance policy'. It contains a 'verifiedOn' field with the date the customer has been verified and a 'notes' field where you can refer to the verification you have done (for example, a contract number).

Some party schemes require an additional verification value before the party identifier can be registered. For those, verification also takes a 'verificationToken' field. For schemes that do not require one, the field is ignored and can be omitted.

Scheme 0245 (Slovakia), for example, requires a DIC verification token. End users can acquire a DIC verfication token through the Slovakia Peppol onboarding portal on E-faktúra - PFS (opens new window) (after login). See Continuous Transaction Controls for the other Slovak requirements.

"verification": {
    "notes": "Contract agreement C21345",
    "verifiedOn": "2020-02-03T14:11:17.2750853+00:00",
    "verificationToken": "9E90C0661F8E5BE4C05014DE2E5BFA6AB98A6F92 ... 5F8C0765495E6"
  }

# Capabilities

Capabilities are the services you want to register in the SMP. We separated the services into document families. The families are 'invoices', 'invoices_bisv2', 'reviews', 'invoiceResponse', 'orders', 'orderResponse', 'orderOnly', 'orderAdvanced' and 'orderResponseAdvanced'. The 'state' field is used to turn these families on or off. Using the 'inherited' value will use the default configuration for your organization. The endpoint api/v1/peppol/config is used to get, add or update the default Peppol configuration for your organization. Use the GET method to get your configuration and the PUT method to add or update a configuration.

"capabilities": {
    "invoices": {
      "state": "on",
      "description": "SI 2.0, SI 2.0 CreditNote, BIS Billing V3, BIS Billing V3 CreditNote, BIS Billing V3 CII"
    },
    "selfbilling": {
      "state": "off",
      "description": "BIS Selfbilling V3, BIS Selfbilling V3 CreditNote"
    },
    "invoice_bisv2": {
      "state": "off",
      "description": "BIS5a Invoice, BIS4a Invoice, BIS5a CreditNote"
    },
    "reviews": {
      "state": "off",
      "description": "PEPPOL MLR 3.0"
    },
    "invoiceResponse": {
      "state": "off",
      "description": "PEPPOL Invoice Response transaction 3.0"
    },
    "orders": {
      "state": "off",
      "description": "PEPPOL Order transaction 3.0"
    },
    "orderResponse": {
      "state": "inherited => off",
      "description": "PEPPOL Order response transaction 3.3"
    },
    "orderOnly": {
      "state": "inherited => off",
      "description": "PEPPOL Order only transaction 3.3"
    },
    "orderAdvanced": {
      "state": "inherited => off",
      "description": "PEPPOL Order transaction 3.3, PEPPOL Order change transaction 3.3, PEPPOL Order cancellation transaction 3.3"
    },
    "orderResponseAdvanced": {
      "state": "inherited => off",
      "description": "PEPPOL Order response advanced transaction 3.3"
  },
  "createdOn": "2020-01-17T08:05:03.3845085+00:00",
  "changedOn": "2020-03-21T04:57:05.6917681+00:00"
}

# Peppol Directory

The businessCard object contains information that will be published in the Peppol Directory (opens new window). The Peppol Directory contains information about entities participating in the Peppol network. The Peppol Directory aggregates public information from SMPs and provides them centrally in a structured way. It enables an accessible way of searching for other participants in Peppol, for example by searching for a company's name. For now only receiving capabilities are listed in the Peppol Directory.

The Peppol Directory registration can be activated or deactivated with the 'state' field. Individual values can also be turned on or off with their own 'state' field. Note that at least one name and a country code are necessary to create a valid business card.

Supply the country in the 'countryCode' field, and the business names in 'names.values', one entry per name. The older conventions remain supported: a country code that is part of the address's 'value' is still picked up when no 'countryCode' is given, and names separated by commas in 'names.value' are still split. A name that itself contains a comma can be wrapped in quotes, so "Firma, s.r.o.", eConnect publishes two names rather than three. See Names and the country code below.

Using the 'inherited' value will use the default configuration for your organization. The endpoint api/v1/peppol/config is used to get, add or update the default Peppol configuration for your organization. Use the GET method to get your configuration and the PUT method to add or update a configuration.

The 'additionalInformation' field holds free text that is published with the business card. The value may not exceed 250 characters and may not contain control characters.

"businessCard": {
    "names": {
      "value": "eVerbinding, eConnect",
      "state": "on",
      "description": "Business names."
    },
    "address": {
      "value": "Pelmolenlaan 16A, 3447 GW, Woerden, NL",
      "state": "on",
      "description": "Geographic information."
    },
    "emailAddress": {
      "value": "techsupport@econnect.eu",
      "state": "on",
      "description": "Technical contact"
    },
    "state": "on"
  },

This businessCard translates to the following entry in the SMP:

<BusinessCard xmlns="http://www.peppol.eu/schema/pd/businesscard/20180621/">
    <ParticipantIdentifier scheme="iso6523-actorid-upis">0106:12345</ParticipantIdentifier>
    <BusinessEntity>
        <Name>eVerbinding</Name>
        <Name>eConnect</Name>
        <CountryCode>NL</CountryCode>
        <GeographicalInformation>Pelmolenlaan 16A, 3447 GW, Woerden, NL</GeographicalInformation>
        <Contact>
            <Email>techsupport@econnect.eu</Email>
        </Contact>
    </BusinessEntity>
</BusinessCard>

# Names and the country code

Everything here is additive: a business card that already works keeps working unchanged.

The country code. 'countryCode' is a sibling of 'address', so the country can be supplied on its own. When it is present, no country is derived from the address and the address is published as geographical information exactly as you typed it. When it is absent the country is still taken from the address, as before. The code is two letters, ISO 3166-1 alpha-2, and is case insensitive.

An address that is nothing but a country code is not published as geographical information at all — the country is already published as 'countryCode', so there is nothing left to say. That applies whether the address repeats the country you supplied or names a different one.

Names as a list. 'names.values' is an array of objects, one per name, each with a 'value'. It is the unambiguous way to publish a name that contains a comma. When 'values' is supplied, 'value' is ignored.

"businessCard": {
    "names": {
      "values": [
        { "value": "Firma, s.r.o." },
        { "value": "eConnect" }
      ],
      "state": "on",
      "description": "Business names."
    },
    "countryCode": {
      "value": "NL",
      "state": "on",
      "description": "ISO 3166-1 alpha-2 country code."
    },
    "address": {
      "value": "Pelmolenlaan 16A, 3447 GW, Woerden",
      "state": "on",
      "description": "Geographic information."
    },
    "state": "on"
  },

This businessCard translates to the following entry in the SMP. Note that Firma, s.r.o. is one name, and that the country appears only in CountryCode, not in the geographical information:

<BusinessCard xmlns="http://www.peppol.eu/schema/pd/businesscard/20180621/">
    <ParticipantIdentifier scheme="iso6523-actorid-upis">0106:12345</ParticipantIdentifier>
    <BusinessEntity>
        <Name>Firma, s.r.o.</Name>
        <Name>eConnect</Name>
        <CountryCode>NL</CountryCode>
        <GeographicalInformation>Pelmolenlaan 16A, 3447 GW, Woerden</GeographicalInformation>
    </BusinessEntity>
</BusinessCard>

Names as a comma separated string. 'names.value' still works. A name containing a comma can be wrapped in quotes to keep it in one piece; only the outer pair is removed, and a pair with no comma inside it is published as typed. Quotes are read in pairs: a comma between an opening and a closing quote belongs to the name, and a quote that never closes protects everything after it — so make sure quoted names are balanced. A trailing comma is treated as part of the name rather than as a separator.

names.value Published names
eVerbinding, eConnect eVerbinding and eConnect
"Firma, s.r.o.", eConnect Firma, s.r.o. and eConnect
Bakkerij "De Molen" Bakkerij "De Molen"
"De Molen" "De Molen", quotes included, since there is no comma for them to protect
Local Heritage BV, Local Heritage BV,
Bakkerij "De Molen, Woerden Bakkerij "De Molen, Woerden — the quote never closes, so it protects the rest

JSON escaping applies on top of this, so to publish Bakkerij "De Molen" you send "value": "Bakkerij \"De Molen\"".

A GET returns 'value', 'values' and 'countryCode' together, and the names in 'value' are quoted where needed, so a configuration you fetched can be sent straight back unchanged.

TIP

'countryCode' also accepts "state": "inherited", which takes the country from your organization's party details without having to inherit the address as well.

# Unregister from Peppol

To unregister, or delete, a party from the Peppol network you can use the DELETE method on the /api/v1/peppol/config/party/{partyId} endpoint. Doing so will remove the partyId from the eConnect SMP and the Peppol SML.

# Migrate

By using the Migrate flow in Peppol, you remain registered in the network, ensuring a seamless transition while reducing the risk of suppliers being unable to send documents.

# Migrate from eConnect

By calling the GET method on the /api/v1/peppol/{partyId}/prepareToMigrate endpoint, you mark the specified partyId for transfer to another Peppol SMP. This process registers the migration key with the Peppol SML.

A migration key will be generated automatically and returned in the API.

# Migrate to eConnect

To migrate a Peppol participant to the eConnect SMP, update the participant’s configuration by adding a migration code. The system will automatically update the SMP configuration and complete the migration process. The migration key needs to be generated by the Peppol SMP to which the SML is currently pointing.

To initiate the migration, add the following to your configuration:

"migration": {
  "key": "YourMigrationKey"
}

If the migration key is invalid, the migration will fail.

← User →

© 2026 eConnect International B.V.