Peppol registration

The Enrollment API is a one-stop shop for registering a new party on the Peppol network. In a single API call you configure the Peppol service, link users with the correct permissions and optionally set up hooks. This article describes the endpoint, the three components of the enrollment and how to remove a registration.

Requirements

The Enrollment API requires the ApManager role. An ApUser cannot perform enrollment. Verify that your API credentials have the correct role before you start.

Role

Permissions

ApUser

Send and receive invoices and orders, manage hooks for own party

ApManager

Everything from ApUser, plus: party registrations, SMP management, enrollment

The Enrollment endpoint

PUT /api/v1-beta/{partyId}/enroll

The {partyId} is the Peppol identifier of the party to register, in the format schemeID:identifier (e.g. 0106:12345678).

The request body contains three sections: Services, Party authorizations and Hooks.

1. Services

In the Services section you activate the Peppol service for the party. You configure the SMP capabilities (which document types the party can receive) and optionally a businessCard for publication in the Peppol Directory.

{
  "services": {
    "peppol": {
      "capabilities": {
        "invoices": "on",
        "invoiceResponse": "on",
        "orderOnly": "inherited"
      },
      "businessCard": {
        "names": "Company Name B.V.",
        "geoInfo": "Utrecht, NL",
        "email": "[email protected]"
      }
    }
  }
}

The businessCard is optional but recommended. Without a businessCard the party will not be discoverable in the Peppol Directory, even though the SMP registration is active.

2. Party authorizations

Here you link one or more users to the party and define their permissions. Each registered party must be linked to at least one ApUser.

{
  "partyAuthorizations": [
    {
      "userId": "[email protected]",
      "permissions": {
        "canSendDocument": true,
        "canReceiveDocument": true,
        "canRemoveDocument": true,
        "canManageHook": true
      }
    }
  ]
}

Permission

Description

canSendDocument

Send documents on behalf of this party

canReceiveDocument

Receive documents for this party

canRemoveDocument

Delete received documents

canManageHook

Create and manage hooks for this party

3. Hooks

Optionally you can register hooks directly for the new party. This is useful if you already know at registration time which notifications are needed, for example a webhook for received invoices.

{
  "hooks": [
    {
      "action": "https://api.company.nl/webhooks/invoices",
      "topics": ["InvoiceReceived"]
    },
    {
      "action": "mailto:[email protected]",
      "topics": ["InvoiceReceived"]
    }
  ]
}

Full example

A complete enrollment request that combines all three components:

{
  "services": {
    "peppol": {
      "capabilities": {
        "invoices": "on",
        "invoiceResponse": "on"
      },
      "businessCard": {
        "names": "Example B.V.",
        "geoInfo": "Amsterdam, NL"
      }
    }
  },
  "partyAuthorizations": [
    {
      "userId": "[email protected]",
      "permissions": {
        "canSendDocument": true,
        "canReceiveDocument": true,
        "canRemoveDocument": false,
        "canManageHook": true
      }
    }
  ],
  "hooks": [
    {
      "action": "https://api.example.nl/learn/peppol/incoming",
      "topics": ["InvoiceReceived"]
    }
  ]
}

Removing a registration

To fully deregister a party (including all services, permissions and hooks), use:

DELETE /api/v1-beta/{partyId}/enroll

After removal, the party is no longer reachable on the Peppol network and all linked hooks and authorizations are cleaned up.

Points of attention

The Enrollment API is a beta endpoint (v1-beta). The functionality is stable, but the endpoint may change in future versions. If you have questions about the beta status, contact TechSupport.

Also keep in mind that the SMP registration may take a few minutes to synchronise across the entire Peppol network after enrollment. This is inherent to the SML/SMP protocol.

Want to take over existing registrations from another provider? Read the article on migration to eConnect.

Try it in the API