/ docs
ProductKnowledgeDevelopers
Platform Control
VPD schema: queries and the party data model

GraphQL queries, the party data model and examples. Aligned with the official PSB schema reference.

The VPD service exposes a GraphQL endpoint. The full, current definition of all queries and types is in the official Schema Reference (partySchema) on the PSB documentation site. In GraphQL, request only the fields you need; the overview and examples below are a practical summary.

Available root queries
QueryPurposepartySearch parties; results ordered by relevancefindBest-effort match when input is uncertain or incomplete (all arguments optional)companyCompany type codes for a given countrysbiSBI codes (Dutch industry classification)naceNACE codes (EU classification)

See the schema reference for full details and types for find, company, sbi and nace.

The party query: parameters
ParameterTypeDescriptionsearchStringFree text across fieldsidStringSearch by identifier (e.g. trade register, VAT or eConnect ID)nameStringSearch by (company) namepostcodeStringFilter by postal codecityStringFilter by citycountryStringCountry code, e.g. NL or BElangStringLanguage for results; defaults to nlmaxResultsIntMaximum results; defaults to 10

You can combine parameters to refine the search.

The party type (core fields)
FieldTypeDescriptionidStringThe party's eConnect IDtypeStringParty typeisActiveBooleanWhether the party is currently activepreferredNameStringLegal name if available; otherwise the first trade namelegalNameStringConfirmed legal name (nullable if not known with certainty)tradeNamesStringTrade namesdescriptionStringShort description of main activitiesidentifierspartyIdentifierIdentifiers (Chamber of Commerce, VAT, GLN, etc.)sectorCodesactivitySector codes (e.g. SBI/NACE)locationslocationKnown locations / addresseswebsiteStringWebsiteeDeliveryeDeliveryElectronic delivery capabilities (including Peppol channels)highlightshighlightHighlighted fragments when search terms match
identifiers: partyIdentifier and partyId

Identifiers are not flat type/value pairs on the root party object. Use identifiers: each item has a name (scheme label, e.g. "KvK") and an id of type partyId with fields such as value, text, schemeIdText, schemeIdNumber and schemeAuthority. See the schema reference for the full list.

Locations

A location includes text (formatted full address), street, number, numberAddition, postcode, city, country (object with iso, etc.) and optional latitude / longitude.

Example queries
Look up by name
{
  party(name: "eConnect", country: "NL", maxResults: 5) {
    id
    preferredName
    legalName
    tradeNames
    identifiers {
      name
      id {
        value
        text
        schemeIdText
      }
    }
  }
}
Search by identifier
{
  party(id: "12345678", maxResults: 1) {
    id
    preferredName
    legalName
    locations {
      text
      street
      postcode
      city
      country {
        iso
      }
      latitude
      longitude
    }
    website
  }
}
Free text search with more detail
{
  party(search: "invoicing Woerden", maxResults: 10) {
    id
    type
    isActive
    preferredName
    legalName
    description
    identifiers {
      name
      id {
        value
        text
      }
    }
    sectorCodes {
      type
      value
      text
      description
    }
    locations {
      text
      postcode
      city
      country {
        iso
      }
    }
    website
  }
}
Uncertain input: find

For fuzzy or incomplete data, use find with an args object (see the documentation for all optional fields, including ids.legal, ids.vat, ids.iban, ids.oin, ids.gln).

{
  find(args: { name: "Gemeente", country: "NL", postcode: "3511" }) {
    eConnectId
    name
    address
    identifiers {
      name
      id {
        value
        text
      }
    }
  }
}
Tips for effective searching

Use search for broad text queries and name or id for tighter filters. Set lang for the language of textual fields (default Dutch). Limit maxResults while testing. Check errors in the GraphQL response for syntax or schema issues; an empty list for party or find means no match, not necessarily an error.

Frequently asked questions
Can I combine several search parameters in one `party` query?

Yes. You can use name together with city, postcode or country to refine results. The official parameter list is in the schema reference.

How do I request identifiers?

Via the identifiers field on party. Select name and the id fields you need (for example value and text). This replaces the older pattern with a flat list partyIds { type value }.

What is the maximum number of results per query?

By default at most 10 results for party, unless you raise maxResults. For a quick check, maxResults: 1 is often enough.

Want to test queries interactively? Use the VPD Playground. Or read how to use the VPD in your integration.

Try the VPD Playground

Related

VPD overview

What the VPD is and what you use it for.

VPD Playground: interactive testing

Write and run GraphQL queries without code.

Using the VPD in your integration

Step by step: authentication, queries and processing.

PreviousVPD overview
NextVPD Playground