Getting started

The Validated Party Data (VPD) service exposes a GraphQL (opens new window) endpoint for querying party information. This endpoint accepts POST requests with a JSON body containing a GraphQL query. The Purple Pages — eConnect's party search application — is built on top of this endpoint; think of the VPD as the API layer and the Purple Pages as the front-end interface that consumes it.

Authentication is required when using the service. When querying for party data, an OAuth bearer token (opens new window) must be added to the request.

Getting a bearer token

Token requests follow the standard eConnect authentication flow — use scope=vpd in place of scope=ap. The example below uses the client credentials grant, which is suitable for service-to-service integrations:

using IdentityModel.Client;

var client = new HttpClient();

var request = new ClientCredentialsTokenRequest
{
    Address = "https://accp-identity.econnect.eu/connect/token",
    ClientId = "{client_id}",
    ClientSecret = "{client_secret}",
    Scope = "vpd"
};

var response = await client.RequestClientCredentialsTokenAsync(request);

if (response.IsError || response.AccessToken == null)
{
    // handle error
}

var token = response.AccessToken;

For the production environment use https://identity.econnect.eu/connect/token (opens new window).

Making a request

Once you have an access token you can send requests to the VPD service. Details on the schema and all available queries are defined in the schema reference chapter.

This simplified example shows the basics of making a request:

using GraphQL;
using System.Net.Http.Json;

var client = new HttpClient();

client.SetBearerToken(token); // your access token

var request = new GraphQLRequest
{
  Query = @"
  {
    party(name:""eConnect"", country:""NL"") {
        preferredName
        website
    }
  }"
};

var content = JsonContent.Create(request);

var response = await client.PostAsync("https://accp-vpd.econnect.eu/graphql/v1", content);

var result = await response.Content.ReadAsStringAsync();

For the production environment use https://vpd.econnect.eu/graphql/v1 (opens new window).

Choosing your query approach

The VPD service offers multiple queries and argument combinations. Which one to use depends on what you know about your data and what you are trying to achieve.

Simple search

Use the search argument when you want a simple, straightfoward search experience — for example, to power a search bar in a user interface. You can pass any combination of terms: a company name, a city, an identifier, or all of them together in a single string. The service uses full-text search across all indexed fields to find the best matches.

{
  party(search: "eConnect Woerden") {
    preferredName
    locations {
      text
    }
    highlights {
      fieldName
      matches
    }
  }
}

The highlights field is particularly useful here: it returns the fragments of each matched field that contain the search terms, which you can use to visually indicate to the user why a result was returned.

You can narrow a search query to a specific region by combining it with a targeted argument — for example search: "eConnect" together with country: "NL".

Structured query

Use the named arguments (name, id, postcode, city, country) when you already know what kind of data you have and want the most accurate results. Each argument targets a specific set of fields rather than searching broadly, so the results are more precise when your input is clean and well-typed.

You can combine as many arguments as you need — they are applied together.

{
  party(name: "eConnect", city: "Woerden") {
    preferredName
    legalName
    identifiers {
      name
      id {
        schemeIdText
        value
      }
    }
    locations {
      street
      number
      postcode
      city
      country { iso }
    }
  }
}

This approach is well suited for system integrations where you are working with structured data and know which value belongs to which field.

Best-effort match

Use the find() query when your data is limited, outdated, or of uncertain quality, and you want the best possible match rather than a precise lookup. You can provide any combination of fields — name, address, and identifiers such as a KvK, VAT number, or IBAN. All fields are optional; the more you provide, the stronger the match.

{
  find(args: {
    name: "eConnect International"
    postcode: "3447GW"
    country: "NL"
    ids: { legal: "54441587" }
  }) {
    eConnectId
    name
    address
    eDelivery {
      accepts {
        channel
        documentName
      }
    }
  }
}

Choosing your fields

GraphQL lets you request exactly the fields you need. Which fields are worth requesting depends on your use case.

Displaying results in a UI

Request preferredName as the display name — it returns the legal name when available, and falls back to the first trade name otherwise. For addresses, location.text gives you a ready-to-display formatted string. The highlights field can be used to show which parts of the result matched the search terms.

Integrating with a CRM or structured system

For structured storage, prefer the individual address fields (street, number, numberAddition, postcode, city) over location.text. For the party name, note that legalName is nullable — it is only set when the legal name is confirmed with certainty. Always request tradeNames alongside it, and consider using preferredName as a safe fallback. For country, location.country.iso gives you the two-letter ISO code suitable for system fields.

Checking eDelivery capabilities

Request the eDelivery field to find out which document types a party can send or receive, and on which channel. The accepts list shows what the party can receive; provides shows what they can send. The channel field tells you the network (e.g. "Peppol"), and documentName gives a human-readable label for the document type.

Enriching records with identifiers

Request identifiers to retrieve all known identifiers for a party. Each entry has a name (the scheme label, such as "KvK" or "VAT") and an id object with the value and scheme details.