Voordat je een factuur of order verstuurt, wil je weten of de ontvanger bereikbaar is. Met het queryRecipientParty endpoint controleer je in één call of een organisatie geregistreerd is op Peppol, welke documenttypen worden geaccepteerd en via welk kanaal de PSB het document zal afleveren. Zo voorkom je verzendfouten en kun je je gebruikers direct feedback geven.

De PSB voert bij elke verzending automatisch een SML/SMP-lookup uit om het juiste Access Point van de ontvanger te vinden. Met queryRecipientParty kun je diezelfde lookup vooraf uitvoeren, zonder daadwerkelijk een document te versturen.

De API controleert:

• Of de ontvanger geregistreerd is in het Peppol-netwerk (SMP-registratie)
• Welke documenttypen de ontvanger kan ontvangen (capabilities)
• Via welk Access Point de aflevering verloopt
• Welk kanaal de PSB zal gebruiken (Peppol, DICO, e-mail fallback, etc.)

GET /api/v1/queryRecipientParty?identifier={schemeID}:{id}

Vervang {schemeID} door het identificatieschema en {id} door het nummer van de ontvanger. Gebruik een van de gangbare Peppol-identifiers:

GET /api/v1/queryRecipientParty?identifier=0106:12345678

Als de ontvanger bereikbaar is, retourneert de API de aanbevolen identifier en het kanaal dat de PSB zal gebruiken:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery"
}

Gebruik de waarde uit id als EndpointID in je UBL-document.

Als de ontvanger niet gevonden wordt op Peppol, retourneert de API een 404 met foutmelding:

{
  "helpLink": "https://psb.econnect.eu/endpoints/v1/SalesInvoice.html#query-recipient-party",
  "message": "PartyId 'NL:KVK:12345678' not found in Peppol.",
  "code": "API404",
  "requestId": "41cd5529904be94d941137068c1c3fa1",
  "dateTime": "2026-03-14T10:22:19.4878393+00:00"
}

Tip: Heeft een organisatie meerdere identifiers (KvK, BTW, OIN)? Probeer een ander schemeID. Niet alle ontvangers zijn onder elke identifier geregistreerd. Voorbeeld: een organisatie is geregistreerd als 0106:12345678 (KvK) maar niet als 0088:5412345678908 (GLN). Krijg je een 404? Probeer altijd het KvK-nummer (0106) of BTW-nummer (9944) als alternatief, of gebruik de POST-variant om meerdere identifiers in één keer te controleren.

Als je meerdere identifiers tegelijk wilt controleren, gebruik dan de POST-variant. De PSB evalueert alle identifiers en retourneert de beste optie:

POST /api/v1/{partyId}/salesInvoice/queryRecipientParty

De {partyId} in de URL is je eigen (verzendende) partyId. In de request body geef je een array van mogelijke identifiers van de ontvanger:

["0106:12345678", "9944:NL123456789B01", "0190:00000001234567890000"]

Dit is handig als je niet weet onder welke identifier de ontvanger geregistreerd is. De API kiest automatisch de beste match.

Met ?includeOptions=true bevat de response een options-array met alle beschikbare afleverkanalen:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery",
  "options": [
    {
      "channel": "peppol",
      "description": "default send via peppol delivery",
      "identifiers": [
        {
          "partyId": {
            "text": "NL:KVK:12345678",
            "value": "12345678",
            "schemeAuthority": "iso6523-actorid-upis",
            "schemeIdText": "NL:KVK",
            "schemeIdNumber": "0106"
          },
          "isValid": true
        }
      ]
    }
  ]
}

Gebruik queryRecipientParty als pre-flight check in de volgende situaties:

• Voor het verzenden: controleer of de ontvanger bereikbaar is voordat je het send-endpoint aanroept, zodat je eindgebruikers directe feedback kunt geven
• Onboarding van relaties: verifieer bij het aanmaken van een nieuwe klant of leverancier of die al op Peppol is geregistreerd
• Multi-channel routing: bekijk welk afleverkanaal de PSB zal selecteren (Peppol, DICO, e-mail) en forceer eventueel een alternatief kanaal via de ?channel parameter bij verzending
• Self-billing: controleer of een leverancier de self-billing capability heeft voordat je een self-billing factuur verstuurt

Let op: De lookup controleert de registratie op het moment van de call. Tussen de lookup en de daadwerkelijke verzending kan een registratie wijzigen. In de praktijk is dit zeldzaam, maar houd er rekening mee bij grote batches met vertraging tussen check en verzending.

Tip: Wil je een SMP-registratie handmatig controleren, los van de API? OpenPeppol biedt de Peppol Lookup Service aan, waarmee je direct de SMP- en Business Card-gegevens van een Peppol-deelnemer kunt opvragen. Handig om te verifiëren of een registratie correct is geconfigureerd.

Wil je ook zien welk Access Point en welke documentformaten een ontvanger precies ondersteunt? Het Peppol delivery options endpoint biedt een gedetailleerder overzicht van de SMP-registratie.

• Peppol-netwerk via de API: SMP en capabilities
• Factuur verzenden via de API
• Peppol-registratie via de API (Enrollment)
• Multi-channel levering configureren
• Wat is Peppol en hoe werkt het netwerk?
• Registreren op Peppol (platform)