API documentation

The following table gives an overview of all available REST interfaces.

NameSinceMethodPathConsumes
Pseudonymizev1.0.0POST/v1/processBundle
Pseudonymize (batch)v2.1.0POST/v1/process/allArray of Bundles
Pseudonymize (Param)v5.1.0POST/entitylist/psn-service/$pseudonymizeParameters
Existsv5.1.0POST/entitylist/psn-service/pseudonym/existsBundle
Depseudonymizev4.0.0POST/v1/resolveBundle
Save Pseudonymv2.1.0POST/entitylist/psn-service/pseudonym/saveParameters
Get Bloomfilterv2.1.0POST/entitylist/psn-service/bloomfilterParameters
Translate Pseudonymv5.3.0POST/entitylist/depsn-service/pseudonym/translateBundle

Pseudonymize

This REST interface accepts a FHIR Bundle as input.

Multi-PSN Support

Since version 2.1.0, multi-psn support is included. This means, that for each entity (e.g. patient), multiple pseudonyms can be created, e.g. on a per project basis. Note that a so-called internal pseudonym is created in any case. This is the pseudonym used in the default case (see below). In case a target system is provided a so-called external pseudonym is created in addition to the internal pseudonym (see below).

Request overview

The following table shows all relevant properties.

PropertyValue
NamePseudonymize
URL/v1/process
Required client roletrustcenter-facade (usage-allowed),
backend-entitylist (usage-allowed)1
Request typePOST
Request parametertargetSystem
Request bodyJSON FHIR Bundle

Response content

The response is a FHIR Bundle with one entry per resource in the input. Each entry contains the pseudonymized resource and an HTTP status.

Resource typeFields returned
PatientPseudonym identifier · gender (if provided) · birthDate (year only)
EncounterPseudonym identifier
OtherPseudonym identifier

Note: For Patient resources, only the birth year is echoed back (e.g. "1970" instead of "1970-02-01"). Month and day are deliberately dropped to limit re-identification risk. No postal address or other IDAT is included in the response.

The pseudonym identifier always has use = secondary and system urn:fdc:difuture.de:trustcenter.plain (or urn:fdc:difuture.de:trustcenter.encrypted when transport encryption is enabled).

Example data

Input
{
   "resourceType":"Bundle",
   "entry":[
      {
         "resource":{
            "resourceType":"Encounter",
            "identifier":[
               {
                  "system":"urn:fdc:example.de:sap",
                  "value":"21001",
                  "period":{
                     "start":"2017-01-01T10:46:19+01:00",
                     "end":"2017-02-01T10:46:19+01:00"
                  }
               }
            ]
         }
      },
      {
         "resource":{
            "resourceType":"Patient",
            "identifier":[
               {
                  "system":"urn:fdc:example.de:sap",
                  "value":"31001"
               }
            ],
            "name":[
               {
                  "use":"official",
                  "family":"Müller",
                  "given":[
                     "Erika"
                  ]
               }
            ],
            "gender":"female",
            "birthDate":"1970-02-01"
         }
      }
   ]
}
Output
{
   "resourceType":"Bundle",
   "entry":[
      {
         "resource":{
            "resourceType":"Encounter",
            "identifier":[
               {
                  "use":"secondary",
                  "system":"urn:fdc:difuture.de:trustcenter.plain",
                  "value":"xGMhL2v0ZHk"
               }
            ]
         },
         "response":{
            "status":"200 OK"
         }
      },
      {
         "resource":{
            "resourceType":"Patient",
            "identifier":[
               {
                  "use":"secondary",
                  "system":"urn:fdc:difuture.de:trustcenter.plain",
                  "value":"0uI_ywlRYKY"
               }
            ],
            "gender":"female",
            "birthDate":"1970"
         },
         "response":{
            "status":"200 OK"
         }
      }
   ]
}

Pseudonymize (batch)

This REST interface provides batch functionality to the Pseudonymize interface. Depending on the configuration, bundles may be processed in parallel.

Request overview

The following table shows all relevant properties.

PropertyValue
NamePseudonymize (batch)
URL/v1/process/all
Required client roletrustcenter-facade (usage-allowed),
backend-entitylist (usage-allowed)1
Request typePOST
Request parametertargetSystem
Request bodyList of JSON FHIR Bundles

Example data

Input
[
   {
      "resourceType":"Bundle",
      "entry":[
         {
            "resource":{
               "resourceType":"Encounter",
               "identifier":[
                  {
                     "system":"urn:fdc:example.de:sap",
                     "value":"21001",
                     "period":{
                        "start":"2017-01-01T10:46:19+01:00",
                        "end":"2017-02-01T10:46:19+01:00"
                     }
                  }
               ]
            }
         }
      ]
   },
   {
      "resourceType":"Bundle",
      "entry":[
         {
            "resource":{
               "resourceType":"Patient",
               "identifier":[
                  {
                     "system":"urn:fdc:example.de:sap",
                     "value":"31001"
                  }
               ],
               "name":[
                  {
                     "use":"official",
                     "family":"Müller",
                     "given":[
                        "Erika"
                     ]
                  }
               ],
               "gender":"female",
               "birthDate":"1970-02-01"
            }
         }
      ]
   }
]
Output
[
   {
      "resourceType":"Bundle",
      "entry":[
         {
            "resource":{
               "resourceType":"Encounter",
               "identifier":[
                  {
                     "use":"secondary",
                     "system":"urn:fdc:difuture.de:trustcenter.plain",
                     "value":"xGMhL2v0ZHk"
                  }
               ]
            },
            "response":{
               "status":"200 OK"
            }
         }
      ]
   },
   {
      "resourceType":"Bundle",
      "entry":[
         {
            "resource":{
               "resourceType":"Patient",
               "identifier":[
                  {
                     "use":"secondary",
                     "system":"urn:fdc:difuture.de:trustcenter.plain",
                     "value":"0uI_ywlRYKY"
                  }
               ],
               "gender":"female",
               "birthDate":"1970"
            },
            "response":{
               "status":"200 OK"
            }
         }
      ]
   }
]

Pseudonymize (param)

This REST interface accepts a FHIR Parameters resource as input. This interface is useful when no master data (such as name) has to be considered. Internally, it follows the same logic as the Pseudonymize interface.

This interface is also supported by miracum/fhir-pseudonymizer.

Request overview

The following table shows all relevant properties.

PropertyValue
NamePseudonymize
URL/entitylist/psn-service/$pseudonymize
Required client roletrustcenter-facade (usage-allowed),
backend-entitylist (usage-allowed)1
Request typePOST
Request parameter-
Request bodyJSON FHIR Parameters

Example data

Input
{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"identifier",
         "valueIdentifier":{
            "system":"urn:fdc:example.de:sap",
            "value":"31001"
         }
      },
      {
         "name":"resourceType",
         "valueCode":"Patient"
      }
   ]
}
Output
{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"pseudonym",
         "valueIdentifier":{
            "use":"secondary",
            "system":"urn:fdc:difuture.de:trustcenter.plain",
            "value":"0uI_ywlRYKY"
         }
      }
   ]
}

Exists

This REST interface accepts the same input as the Pseudonymize interface, i.e. a FHIR Bundle. The interface may be used to check whether a pseudonym for a specific patient already exists.

Request overview

The following table shows all relevant properties.

PropertyValue
NameExists
URL/entitylist/psn-service/pseudonym/exists
Required client roletrustcenter-facade (usage-allowed),
backend-entitylist (usage-allowed)2
Request typePOST
Request parameter-
Request bodyJSON FHIR Bundle

Example data

Input
{
   "resourceType":"Bundle",
   "entry":[
      {
         "resource":{
            "resourceType":"Encounter",
            "identifier":[
               {
                  "system":"urn:fdc:example.de:sap",
                  "value":"21001",
                  "period":{
                     "start":"2017-01-01T10:46:19+01:00",
                     "end":"2017-02-01T10:46:19+01:00"
                  }
               }
            ]
         }
      },
      {
         "resource":{
            "resourceType":"Patient",
            "identifier":[
               {
                  "system":"urn:fdc:example.de:sap",
                  "value":"31001"
               }
            ],
            "name":[
               {
                  "use":"official",
                  "family":"Müller",
                  "given":[
                     "Erika"
                  ]
               }
            ],
            "gender":"female",
            "birthDate":"1970-02-01"
         }
      }
   ]
}
Output
{
   "resourceType":"Bundle",
   "entry":[
      {
         "resource":{
            "resourceType":"Encounter",
            "identifier":[
               {
                  "use":"secondary",
                  "system":"urn:fdc:difuture.de:trustcenter.plain",
                  "value":"xGMhL2v0ZHk"
               }
            ]
         },
         "response":{
            "status":"302 FOUND"
         }
      },
      {
         "response":{
            "status":"404 NOT_FOUND",
            "outcome":{
               "resourceType":"OperationOutcome",
               "issue":[
                  {
                     "severity":"information",
                     "code":"not-found",
                     "diagnostics":"No pseudonym found for this identifier."
                  }
               ]
            }
         }
      }
   ]
}

Depseudonymize

This REST interface accepts a FHIR Bundle with a list of entries containing any type of FHIR resource. It is expected that each resource contains a pseudonym as identifier, i.e. they system of the identifier has to be urn:fdc:difuture.de:trustcenter.plain.

Request overview

The following table shows all relevant properties.

PropertyValue
NameDepseudonymize
URL/v1/resolve
Required client roletrustcenter-facade (usage-allowed),
trustcenter-facade (default-case-allowed)3,
trustcenter-facade (all-systems-allowed)4,
trustcenter-facade (<any-target-system>)1 5
Request typePOST
Request parametertargetSystem
Request bodyJSON FHIR Bundle

Example data

Input
{
   "resourceType":"Bundle",
   "entry":[
      {
         "resource":{
            "resourceType":"Encounter",
            "identifier":[
               {
                  "use":"secondary",
                  "system":"urn:fdc:difuture.de:trustcenter.plain",
                  "value":"xGMhL2v0ZHk"
               }
            ]
         }
      },
      {
         "resource":{
            "resourceType":"Patient",
            "identifier":[
               {
                  "use":"secondary",
                  "system":"urn:fdc:difuture.de:trustcenter.plain",
                  "value":"0uI_ywlRYKY"
               }
            ]
         }
      },
      {
         "resource":{
            "resourceType":"Patient",
            "identifier":[
               {
                  "use":"secondary",
                  "system":"urn:fdc:difuture.de:trustcenter.plain",
                  "value":"some-unknown-psn"
               }
            ]
         }
      }
   ]
}
Output
{
   "resourceType":"Bundle",
   "entry":[
      {
         "resource":{
            "resourceType":"Encounter",
            "identifier":[
               {
                  "system":"urn:fdc:example.de:sap",
                  "value":"21001",
                  "period":{
                     "start":"2017-01-01T09:46:19+00:00",
                     "end":"2017-02-01T09:46:19+00:00"
                  }
               }
            ]
         },
         "response":{
            "status":"200 OK"
         }
      },
      {
         "resource":{
            "resourceType":"Patient",
            "identifier":[
               {
                  "system":"urn:fdc:example.de:sap",
                  "value":"31001"
               }
            ],
            "name":[
               {
                  "use":"official",
                  "family":"Müller",
                  "_family":{
                     "extension":[
                        {
                           "url":"http://hl7.org/fhir/StructureDefinition/humanname-own-name",
                           "valueString":"Müller"
                        }
                     ]
                  },
                  "given":[
                     "Erika"
                  ]
               }
            ],
            "gender":"female",
            "birthDate":"1970-02-01"
         },
         "response":{
            "status":"200 OK"
         }
      },
      {
         "response":{
            "status":"204 NO_CONTENT",
            "outcome":{
               "resourceType":"OperationOutcome",
               "issue":[
                  {
                     "severity":"warning",
                     "code":"not-found",
                     "diagnostics":"Pseudonym for 'Patient' does not exist."
                  }
               ]
            }
         }
      }
   ]
}

Save Pseudonym

This REST interface accepts a FHIR Parameters resource as input. This interface can be used to save pseudonyms that have been generated elsewhere.

Pseudonyms must be project-specific, i.e. target-system must be specified.

Request overview

The following table shows all relevant properties.

PropertyValue
NameSave Pseudonym
URL/entitylist/psn-service/pseudonym/save
/psns/psn-service/pseudonym/save (2nd level)
Required client rolebackend-entitylist (usage-allowed)
backend-pseudonymization (usage-allowed) (2nd level)
Request typePOST
Request parameterresourceType
Request bodyJSON FHIR Parameters

Example data

Input
{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"target-system",
         "valueString":"MVH"
      },
      {
         "name":"internal-psn",
         "valueString":"0uI_ywlRYKY"
      },
      {
         "name":"external-psn",
         "valueString":"PSN-1"
      }
   ]
}

Get Bloomfilter

This REST interface accepts a FHIR Parameters resource as input.

The optional profile parameter selects the bloom filter profile to use:

  • numcodex — the default profile (available since v2.1.0); used when no profile parameter is provided
  • eyematics — added in v5.3.0

Both profiles must be individually enabled via configuration (BF_NUMCODEX_ENABLED / BF_EYEMATICS_ENABLED). See the configuration options for all BF_NUMCODEX_* and BF_EYEMATICS_* parameters.

Request overview

The following table shows all relevant properties.

PropertyValue
NameGet Bloomfilter
URL/entitylist/psn-service/bloomfilter
Required client rolebackend-entitylist (usage-allowed)
Request typePOST
Request parameter-
Request bodyJSON FHIR Parameters

Example data

Input
{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"internal-psn",
         "valueString":"0uI_ywlRYKY"
      },
      {
          "name": "profile",
          "valueString": "eyematics"
      }
   ]
}
Output
{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"internal-psn",
         "valueString":"0uI_ywlRYKY"
      },
      {
         "name":"bloomfilter",
         "valueString":"zBXNRnyaV+SBhI1tHnYqheOlsrtY3ML7Tq7elvgG5LRa98EvBN6o3ir42Flb8MGX33bioVdlX3c5cnh1TpKNY+HONvXtke5R+zxVezT7Sc2oMD90RPjqWJw0JUinDTKMwZTVs4dDHTFexCgsk+rpl1/wvxHNMOaI5vQWNRxc8lH2l6rwsOIKE5KQOVS07KOgSzSdsIyyj04pCtwwC3K76kgMgBrEJdvEaGqBp48Qjt+YLStvyGDXuUcwkeN9cjk2I13Vnoli2Cc0mGTuLDNKr3LdiJsPokliTWLCZbhT6OjbkDi7vVZ7dnDPGLFzPHVZ9CsL0GCdJfoCzg=="
      }
   ]
}

Translate Pseudonym

This REST interface resolves an external (project-based) pseudonym to its corresponding internal pseudonym, without reversing to patient data (IDAT). It accepts a FHIR Bundle containing a resource with a known external pseudonym identifier.

Request overview

PropertyValue
NameTranslate Pseudonym
URL/entitylist/depsn-service/pseudonym/translate
Required client rolebackend-depseudonymization (usage-allowed)
Request typePOST
Request parametertargetSystem
Request bodyJSON FHIR Bundle

Example data

Input
{
   "resourceType":"Bundle",
   "entry":[
      {
         "resource":{
            "resourceType":"Patient",
            "identifier":[
               {
                  "use":"secondary",
                  "system":"urn:fdc:difuture.de:trustcenter.plain",
                  "value":"0uI_ywlRYKY"
               }
            ]
         }
      }
   ]
}
Output (pseudonym found)

HTTP 200 OK — Bundle with the pseudonym for the requested target system.

Output (pseudonym not found)

HTTP 207 Multi-Status — Bundle with a 404 Not Found status per entry that could not be resolved.

  1. Since v5.0.0. ↩︎ ↩︎ ↩︎ ↩︎

  2. Since v5.1.0. ↩︎

  3. This role enables access to the depseudonymization interface in case no target-system is specified as query parameter. ↩︎

  4. This role enables access to the depseudonymization interface in case a target-system was specified as query parameter (any target-system is allowed). ↩︎

  5. This role enables access to the depseudonymization interface when specifying a specific target-system as query parameter. ↩︎

Prev
Architecture
Next
Authentication