Using the VPD in your integration

Integrating Validated Party Data into your application: authentication, queries and processing.

This article describes how to integrate the Validated Party Data (VPD) service into your application. From setting up authentication to processing search results: all the steps to programmatically look up and verify party data.

Step 1: obtain an OAuth2 token

Request an access token from the eConnect identity server using the Client Credentials flow. Use scope vpd:

POST https://identity.econnect.eu/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your-client-id
&client_secret=your-client-secret
&scope=vpd

The token is valid for 3600 seconds by default. Read expires_in in the response and refresh the token before it expires. For testing, use the acceptance environment: accp-identity.econnect.eu.

Step 2: send a GraphQL query

Send a POST request to the VPD endpoint with your query in the body:

POST https://vpd.econnect.eu/graphql/v1
Authorization: Bearer {your-access-token}
Content-Type: application/json

{
  "query": "{ party(name: \"Gemeente Utrecht\", maxResults: 5) { legalName preferredName identifiers { name id { value text } } locations { city } } }"
}

The VPD returns a JSON response with a data object; under the root field you queried (here: party) you get a list of matches.

Step 3: process the response

A typical response looks like this:

{
  "data": {
    "party": [
      {
        "legalName": "Gemeente Utrecht",
        "preferredName": "Gemeente Utrecht",
        "identifiers": [
          {
            "name": "KvK",
            "id": { "value": "12345678", "text": "12345678" }
          },
          {
            "name": "OIN",
            "id": { "value": "00000001002306608000", "text": "00000001002306608000" }
          }
        ],
        "locations": [
          { "city": "Utrecht" }
        ]
      }
    ]
  }
}

Iterate over the list under party to process the results. Each item contains the fields you selected in your query. The exact data model is in the VPD schema reference.

Practical integration scenarios
Debtor validation when invoicing

Before sending an invoice, you can use the VPD to check whether the recipient exists and has the correct identifiers. Search by Chamber of Commerce number or company name and compare the result with the data in your own system. This prevents invoices from being sent to a wrong address or a non-existent organisation.

Address enrichment during onboarding

When a new business relation is created in your system, you can query the VPD to automatically populate the registered address, trade names and sector. This speeds up onboarding and improves data quality.

Identifier lookup for Peppol delivery

To send an invoice via Peppol, you need the correct schemeID and identifier. The VPD returns all known identifiers of an organisation (KvK, OIN, VAT, GLN), so you can select the right routing address.

Error handling

If a query returns no results, the VPD returns an empty list for the root field you used (e.g. party or find). For invalid queries, the API returns an errors array with a description of the problem. Always check whether the response contains an errors field before processing the data.

For authentication errors (expired or invalid token), the API returns an HTTP 401. In that case, refresh your access token and try again.

Acceptance and production
ComponentAcceptanceProductionIdentity serveraccp-identity.econnect.euidentity.econnect.euVPD endpointaccp-vpd.econnect.eu/graphql/v1vpd.econnect.eu/graphql/v1Playgroundaccp-vpd.econnect.euvpd.econnect.eu

Always test your integration on the acceptance environment first. The data in acceptance may differ from production.


Need help setting up your VPD integration? Contact TechSupport or check the API documentation at psb.econnect.eu.

Try the VPD Playground