API Versioning for Person API

The Person API follows semantic versioning principles using a Major.Minor scheme. While we continuously deploy new functionality, breaking changes are carefully managed through version control. All changes are documented in the Changelog.

Legacy versions remain available for 6 months after deprecation notice.

Version Selection

The version of the API is specified in the URL:

/api/v3/<scope>/<method-name>

where <scope> is either full-access or restricted-access, and <method-name> is the part of the API, for example person, event or search.

Example:

GET /api/v3/full-access/person/12345678910

The api-version HTTP header is not required, since the version is already specified in the URL.

Version 2 and earlier

Version 2 and version 1 have been removed. Support for older versions of the API was discontinued permanently on 05.05.2026, and only version 3 is available.

Version Types

Major Versions (Breaking Changes)

A major version increment (X.0) indicates breaking changes that require client updates. Examples include:

• Significant information model changes
• Technical corrections
• Infrastructure updates
• Security improvements

When we release a new major version:

• Both versions run concurrently during the transition period
• Clients have 6 months to migrate to the new version
• Clear migration guides are provided

Minor Versions (Non-Breaking Changes)

A minor version increment (1.X) indicates backwards-compatible changes such as:

• New endpoints
• Additional data fields
• Optional parameters
• Enhanced functionality

Existing integrations continue to function without modification, though updates may be needed to utilize new features.

What changed in version 3

Version 3 introduced breaking changes compared to version 2:

• New endpoint URL format: /api/v3/<scope>/<method-name> (replacing /api/<scope>/<method-name>)
• DPoP authentication is mandatory. See: DPoP Authentication Guide
• New scopes: nhn:hgd-persontjenesten-api/full-access and nhn:hgd-persontjenesten-api/restricted-access, replacing nhn:hgd-persontjenesten-api/read-with-legal-basis and nhn:hgd-persontjenesten-api/read-no-legal-basis
• Empty fields (null values) are omitted from the response

See the Changelog for details on other changes.