entici

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
Existsv5.1.0POST/entitylist/psn-service/pseudonym/existsBundle
Depseudonymizev4.0.0POST/v1/resolveBundle
Pseudonymize (Param)v5.1.0POST/entitylist/psn-service/$pseudonymizeParameters
Save Pseudonymv2.1.0POST/entitylist/psns-service/pseudonym/saveParameters
Get Bloomfilterv2.1.0POST/entitylist/psns-service/bloomfilterParameters

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

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"
            }
         }
      ]
   }
]

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."
                  }
               ]
            }
         }
      }
   ]
}

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.

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"
         }
      }
   ]
}

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/backend/pseudonym/save
/psns/backend/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.

Request overview

The following table shows all relevant properties.

PropertyValue
NameGet Bloomfilter
URL/entitylist/backend/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"
      }
   ]
}
Output
{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"internal-psn",
         "valueString":"0uI_ywlRYKY"
      },
      {
         "name":"bloomfilter",
         "valueString":"zBXNRnyaV+SBhI1tHnYqheOlsrtY3ML7Tq7elvgG5LRa98EvBN6o3ir42Flb8MGX33bioVdlX3c5cnh1TpKNY+HONvXtke5R+zxVezT7Sc2oMD90RPjqWJw0JUinDTKMwZTVs4dDHTFexCgsk+rpl1/wvxHNMOaI5vQWNRxc8lH2l6rwsOIKE5KQOVS07KOgSzSdsIyyj04pCtwwC3K76kgMgBrEJdvEaGqBp48Qjt+YLStvyGDXuUcwkeN9cjk2I13Vnoli2Cc0mGTuLDNKr3LdiJsPokliTWLCZbhT6OjbkDi7vVZ7dnDPGLFzPHVZ9CsL0GCdJfoCzg=="
      }
   ]
}

  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 depseudoynmization interface when specifying a specific target-system as query parameter. ↩︎

Prev
Quick Start
Next
Configuration