FHIR API¶
vfps implements the MII pseudonymization interface, the FHIR API the Medizininformatik-Initiative specifies for pseudonymization services. Its operations work on a pseudonymization context, which in vfps is a namespace: the context's identifier value is the namespace name.
Base URL and versioning¶
Version 2026 of the interface is served at the FHIR base URL /fhir/mii/2026:
| Request | Purpose |
|---|---|
POST /fhir/mii/2026/$<operation> |
Invoke one operation on a single value |
POST /fhir/mii/2026 |
Process a batch Bundle of operations |
GET /fhir/mii/2026/metadata |
The CapabilityStatement |
The 2026 is the interface's major version, which it raises for every breaking change. Minor and
patch releases of the implementation guide stay compatible, so they are served from the same base
URL, and only the CapabilityStatement names the exact release, as
implementationGuide: https://www.medizininformatik-initiative.de/fhir/ext/mii-interface-module-pseudonymization|2026.1.0.
A later major version will get a base URL of its own, served next to this one.
Requests and responses are FHIR R4 JSON (application/fhir+json). With authorization enabled,
every request, metadata included, needs a bearer token - see
Authenticating API calls.
Operations¶
| Operation | Does | Context | Requires |
|---|---|---|---|
$pseudonymize |
Returns the pseudonym of an original value, creating it if there is none yet | Single-pseudonym | Write |
$get-pseudonym |
Returns the pseudonym of an original value, creating nothing | Single-pseudonym | Write |
$pseudonymize-multiple |
With a count above 0, adds that many new pseudonyms and returns them; with 0, returns all stored ones |
Multi-pseudonym | Write |
$de-pseudonymize |
Returns the original value of a pseudonym | Either | Reverse-lookup |
$delete-pseudonym |
Not implemented yet - answers 501 Not Implemented |
- | - |
$anonymize-original |
Not implemented yet - answers 501 Not Implemented |
- | - |
A context is a multi-pseudonym context when its namespace
allows multiple pseudonyms per original value,
and a single-pseudonym context otherwise. Calling an operation on a context of the other kind is
answered with a 422 - the single-pseudonym operations don't fall back to the first of several
pseudonyms, the way the /v1/fhir operations do. $pseudonymize-multiple
adds at most 100 pseudonyms per call, and every call with a count above 0 adds new ones - it is
not safe to retry.
$get-pseudonym needs write access, not read access, for the same reason the REST API's
:resolve does: telling whether a value already has a pseudonym reveals whether it was ever in
the namespace. The CapabilityStatement lists the four implemented operations only.
Parameters¶
Every operation takes a Parameters resource whose inputs are Identifiers, each given exactly
once - lists are processed as batch Bundles:
context- itsvalueis the namespace name.original- itsvalueis the original value.pseudonym($de-pseudonymize) - itsvalueis the pseudonym.count($pseudonymize-multiple) - aninteger.
The system of each Identifier is optional and doesn't affect what is looked up or stored. Where a
response repeats an input parameter, it is returned exactly as it was sent. A pseudonym that
$pseudonymize, $get-pseudonym or $pseudonymize-multiple returns takes the system of the
context, and the original value $de-pseudonymize returns has none, because vfps stores the value
alone.
curl -X POST 'http://localhost:8080/fhir/mii/2026/$pseudonymize' \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{ "name": "context", "valueIdentifier": { "system": "https://example.org/psn", "value": "test" } },
{ "name": "original", "valueIdentifier": { "value": "to be pseudonymized" } }
]
}'
{
"resourceType": "Parameters",
"parameter": [
{
"name": "context",
"valueIdentifier": {
"system": "https://example.org/psn",
"value": "test"
}
},
{
"name": "original",
"valueIdentifier": { "value": "to be pseudonymized" }
},
{
"name": "pseudonym",
"valueIdentifier": {
"system": "https://example.org/psn",
"value": "fk6r7kQ1..."
}
}
]
}
Processing lists¶
To process several values in one request, post a batch Bundle to the base URL, with one entry per
value. Each entry's request names the operation, relative to the base URL, and its resource is
that operation's Parameters:
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Parameters",
"parameter": [
{ "name": "context", "valueIdentifier": { "value": "test" } },
{ "name": "original", "valueIdentifier": { "value": "first value" } }
]
},
"request": { "method": "POST", "url": "$pseudonymize" }
}
]
}
The response is a batch-response Bundle with one entry per request entry, in the same order. Every
entry is processed on its own and carries its own response.status, so one value that fails
doesn't stop the others: a successful entry holds the operation's Parameters, a failed one an
OperationOutcome in entry.resource, where the implementation guide's examples put it. A batch
holds at most 10,000 entries.
Entries run concurrently and in no particular order, so - as FHIR requires of a batch anyway - no
entry may depend on another: a $get-pseudonym for a value that an earlier entry of the same batch
pseudonymizes may or may not find it. An entry that isn't a POST gets a 405 of its own, one naming no
known operation a 404. transaction Bundles, which would process the list all or nothing, are not
supported and are answered with a 400.
Errors¶
Every error is answered with an OperationOutcome, except a request without a bearer token, which
the request pipeline refuses before the API sees it.
| Status | Meaning |
|---|---|
400 |
The body isn't a valid resource of the expected type, a parameter is missing, of another type, blank or repeated, or a Bundle is a transaction or holds too many entries |
401 |
No bearer token, with no body |
403 |
The token holds no grant for the permission the operation needs |
404 |
The context doesn't exist, or holds no pseudonym for the value. $de-pseudonymize doesn't tell the two apart |
422 |
The namespace refuses the request: the value fails its validation pattern or is missing from its parent namespace, the context is of the wrong kind, or the namespace uses the External generation method |
500 |
An unexpected error, such as a pseudonym that couldn't be stored after several retries |
501 |
$delete-pseudonym and $anonymize-original, which are not implemented yet |
An OperationOutcome never contains an original value, so it is safe to log.
The /v1/fhir operations¶
Before the MII interface, vfps offered two operations of its own at /v1/fhir, which are still
served: $create-pseudonym and $resolve-pseudonym take string namespace and originalValue
parameters and answer with a pseudonymValue, and always work on the first pseudonym of a
multi-pseudonym namespace. New clients should use the MII interface.