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.
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.
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.
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.
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.
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.
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.
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.
accp-identity.econnect.euidentity.econnect.euaccp-vpd.econnect.eu/graphql/v1vpd.econnect.eu/graphql/v1accp-vpd.econnect.euvpd.econnect.euAlways 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