API docs by Redocly

Mainzelliste API (3.3.0)

Download OpenAPI specification:Download

Mainzelliste: info@mainzelliste.de URL: http://mainzelliste.de

Introduction

Mainzelliste provides a REST-based interface for the pseudonymization of personal data and management of consents to ensure privacy-compliant data processing. This interface supports the following use cases:

  • First-level pseudonymization (IDAT → PID)
  • Management of multiple pseudonyms (e.g., PSN, SIC, DeineID1, DeineID2, ...)
  • Name resolution (Pseudonym → IDAT)
  • Handling of temporary pseudonyms
  • Batch pseudonymization
  • Consent management

This document includes:

  1. An introductory example, which presents the key elements of the interface using a typical use case. This section is particularly useful for newcomers as an entry point to working with the interface.
  2. A formal specification of the interface, intended as a reference for developers implementing the interface on either the client or server side, and as a comprehensive overview of its functionality. Note: Endpoints tagged as EXPERIMENTAL are subject to change or removal in future releases.

Cite as

For referencing the Mainzelliste interface in publications, you may cite the open-access article published in 2015 in BMC Medical Informatics and Decision Making [1].

License, Distribution, Modification

Mainzelliste is free software; see http://www.mainzelliste.de. The interface specified here is open, meaning its specification is publicly available and may be implemented without our permission. Extensions or modifications are also permitted. However, in the interest of maintaining a consistent interface in the long term, we kindly ask that you discuss any proposed changes with us before distributing modified versions. Until now, we have been able to include all suggestions into this official interface specification.

Resources

The REST paradigm uses the HTTP protocol for communication and processes the following REST resources:

  • patients – The patients along with their identifying attributes and identifiers.
  • sessions – Represent a user session to group tokens.
  • tokens – Represent permissions for accessing functions of the interface.
  • jobs - Represent asynchronous job. Batch pseudonymiziation of multiple patients.
  • fhir/Consent - Consent fhir resource according to HL7 FHIR R4 specification.
  • fhir/Provenance - Provenance fhir resource includes digital signatures and references to pdf scans.
  • fhir/DocumentReference - DocumentReference fhir resource containing consent related pdf scans.
  • html – Predefined HTML forms for display in a web browser.

Introduction Example

The following example illustrates the basic functionality of the interface. The scenario is as follows:

  • A registry is used to pseudonymize and store medical data (MDAT) of study participants. The registry provides a web interface (HTML) through which MDAT, along with the corresponding pseudonym (referred as “ID”), can be submitted. The registry software includes user management and authentication (e.g., via username and password).
  • The MDAT is collected from multiple participating clinics. Each clinic holds the identifying data (IDAT) of the registry patients treated at their facility.
  • To enable cross-institutional tracking of patients, a central patient list is used for pseudonymization, accessed via the interface described here. Authorized personnel at the clinics enter the patients’ IDAT into the system. The patient list uses a record linkage algorithm to check whether the patient is already registered. If the patient exists, the existing pseudonym is returned. If not, the IDAT is stored and a new pseudonym is generated and returned.

Sequence Diagram of the Introduction Example

The following describes the case in which a user wants to enter a new patient into the registry software and request a pseudonym for that patient. This process is illustrated in the sequence diagram in Figure 1. The numbers in the following notes refer to steps in this diagram.

Authentication and Authorization

The Mainzelliste interface does not perform separate authentication of individual users, as this is typically handled by another server. In this context, it is assumed that authentication is performed by the web server of the MDAT application (here referred to as the "MDAT server"). The MDAT server authenticates itself to the patient list and issues access tokens to users, thereby implementing a single sign-on (SSO) concept. Steps 1–4 in the sequence diagram illustrate this concept:

  1. The user logs into the MDAT server, for example using a username and password or a smartcard certificate. The MDAT server then creates a browser session for the user.
  2. The MDAT server creates a session in Mainzelliste. This serves as an extension of the user's browser session across an additional server. The session is created by sending a POST request to the */sessions/* resource of the Mainzelliste. The MDAT server authenticates itself using an access key (which is configured in the patient list), provided via the HTTP header *mainzellisteApiKey*. The session is assigned a unique identifier *{sessionId}* and a resource path */sessions/{sessionId}/*. The full URL of the session is returned to the MDAT server.
  3. The user selects the “New Patient” function.
  4. To authorize the user to pseudonymize a patient, the MDAT server creates an access token on the patient list. Tokens are represented within a session by the path */tokens/*. A token is created via a POST request to the resource */sessions/{sessionId}/tokens/*. The most important properties of a token are:
    1. Token type (type parameter in the submitted object): This is an identifier that defines the function for which the token is valid. In this case, the type *addPatient* is used, which authorizes pseudonymization of exactly one patient.
    2. Token ID: This identifier uniquely represents the token. To redeem the token (i.e., to invoke a function of the Mainzelliste), only the token ID is required. It is implemented as a sufficiently long random string to prevent collisions and make guessing practically impossible.
    The token is returned as a JSON object, allowing the MDAT server to extract the token ID from the response.

By using access tokens, the Mainzelliste can bypasse the management of individual user accounts. This avoids the duplication of user information, which already exists on the MDAT server, and simplifies the administration of the Mainzelliste by external service providers.

Pseudonymization

The actual pseudonymization must now be performed by the user on a webpage provided by the patient list. Entering identifying data (IDAT) into a form delivered by the MDAT server would violate the strict separation of medical and identifying data, as the MDAT server could potentially access the IDAT. The process proceeds as follows: 5. The MDAT server redirects the user to the /html/createPatient resource of the patient list, for example via an HTTP redirect or a hyperlink. The token ID created in step (4) is appended as a URL parameter tokenID. As response, the patient list serves an HTML form in which the user can enter the identifying data of the new patient. 6. When the form is submitted, the entered data is sent via a POST request to the /patients resource. As in the previous step, the token ID is passed as a URL parameter. To authorize the request, the patient list verifies that a token with this ID exists and is valid (i.e., has not yet been used). 7. The patient list determines a pseudonym for the patient — either an existing one, if a matching patient is already exist, or a new one if the patient is not yet registered. 8. The pseudonym is displayed to the user, who can then record it and use it to enter medical data into the MDAT application.

References

[1] Lablans M, Borg A, Ückert F (2015) A RESTful interface to pseudonymization services in modern web applications. BMC Med Inform Decis Mak 15: 2. doi: 10.1186/s12911-014-0123-5

Output status information as JSON.

Responses

Response samples

Content type
{
  • "distname": "Mainzelliste",
  • "version": "1.9.0"
}

Get a list of patients.

Retrieve a list of all patients to whom the provided token grants access. The token specifies which patients and which data (IDAT, IDs) of these patients are retrieved.

query Parameters
tokenId
required
string

Id of a valid "readPatients" token. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "readPatients",
  "allowedUses": "10",
  "data": {
    "searchIds": [
      {
        "idType":"pid",
        "idString":"8HKL6P7"
      }
    ],
    "resultFields":["vorname", "nachname", "geburtstag", "geburtsmonat", "geburtsjahr"],
    "resultIds":["extId"]
  }
}
page
integer

This is the result page number, if the client decide to return the result in a series of pages. This parameter have to be used together with "limit" query parameter. Both of them must be positive

limit
integer

This limit the number of results per page. This parameter have to be used together with "page" query parameter. Both of them must be positive

object

using a configured field name instead of as query parameter allows filtering of returned results.

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Create a patient and assign IDs to them.

This operation checks whether a patient with the given identifying data already exists in the database. If not, a new patient is created, and the requested ID in the addPatient token are generated and returned or forwarded for this patient. If yes, the existing IDs are used. For the caller, it is not discernible whether the patient already existed or was newly created. Check if a patient with the given identifying data exists in the database. If not sure (true) whether the data corresponds to an existing patient or a new entry, perform the following:

  • sureness: true: Create a new patient. Generate the IDs as tentative (field "tentative," see ID section). This signals that a subsequent merge with an existing record is possible.
  • sureness: false: Check if the patient already exists and use the existing IDs.
query Parameters
tokenId
required
string

Id of a valid "addPatient" token. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "addPatient",
  "allowedUses": "10",
  "data": {
    "idtypes":["pid"]
  }
}
header Parameters
mainzellisteApiVersion
string

Version of Mainzelliste API.

Request Body schema:
required
fields
object

configured IDAT field

ids
object

list of external Ids. Multiple external ID type must given as an array

sureness
boolean
Default: false

This automate the decision, when an unsure match happen, and determine whether the tentative patient should be add or not. If true generate IDs as tentative (field "tentative") and also mark the patient as tentative to signal that a subsequent merge with an existing record is possible. Otherwise the request will be rejected

ignoreInvalidIDAT
boolean
Default: false

This allows adding patient with invalid IDAT for subsequent corrections. As the IDAT not suitable for record linkage an external ID would berequired to ensure a feature linkage with existing patients.

Responses

Request samples

Content type
{
  • "fields": {
    },
  • "ids": {
    },
  • "sureness": false,
  • "ignoreInvalidIDAT": false
}

Response samples

Content type
[
  • {
    }
]

Edit existing Patient

The dataset of the patient provided during token creation is modified as follows:

  • All fields and IDs that are included in the call with a non-empty value are set to the provided value.
  • Fields and IDs that are included in the call with an empty value (null or an empty string) are deleted. The field content is set to an empty string even if null is passed as input.
  • Fields and IDs that are not included in the call (i.e., the field name is not present as a key) are not changed.
  • Validation functions that affect the fields to be changed are applied. If date validation is configured, it may also consider non-changing fields (example: attempting to set the birth month to "02" for a patient with a birthdate of 30.01.2000 will fail). If any single validation fails, the entire call has no effect.
query Parameters
tokenId
required
string

Id of a valid "editPatient" token. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "editPatient",
  "data": {
    "patientId": {
      "idType":"pid",
      "idString":"0003Y0WZ"
    },
    "fields":[ "nachname", "geburtsname", "plz", "ort", "geburtstag", "geburtsmonat", "geburtsjahr"],
    "ids": ["extid"]
  }
}
header Parameters
mainzellisteApiVersion
string

version of mainzelliste api.

Request Body schema:
required
field
string
externalId
string

Responses

Request samples

Content type
{
  • "vorname": "Max",
  • "nachname": "Mustermann",
  • "geburtstag": "13",
  • "geburtsmonat": "01",
  • "geburtsjahr": "1891",
  • "edcExtId": "154521114"
}

DELETE patients

delete a patient and anonymize entries in IDRequest database table.

query Parameters
tokenId
required
string

Id of a valid deletePatient token containing a valid "idType" and "idString" of the patient to be deleted. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

  {
    "type": "deletePatient",
    "data": {
      "patientId": {
        "idType": "pid",
        "idString": "0003Y0WZ"
      },
    }
  }

Responses

Get a list of patients. Deprecated

Retrieve a list of all patients to whom the provided token grants access. The token specifies which patients and which data (IDAT, IDs) of these patients are retrieved.

path Parameters
tokenId
required
string

Id of a valid "readPatients" token.

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Create a patient and assign IDs to them. Deprecated

It is checked whether a patient with the given identifying data already exists in the database. If not, a new patient is created, and the configured IDs are generated and returned or forwarded for this patient. If yes, the existing IDs are used. For the caller, it is not discernible whether the patient already existed or was newly created. Check if a patient with the given identifying data exists in the database. If not sure (true) whether the data corresponds to an existing patient or a new entry, perform the following:

  • sureness: true: Create a new patient. Generate the IDs as tentative (field "tentative," see ID section). This signals that a subsequent merge with an existing record is possible.
  • sureness: false: Check if the patient already exists and use the existing IDs.
path Parameters
tokenId
required
string

Id of a valid "addPatient" token.

header Parameters
mainzellisteApiVersion
string

Version of Mainzelliste API.

Request Body schema: application/x-www-form-urlencoded
required
sureness
boolean
Default: false

Responses

Response samples

Content type
[
  • { }
]

Edit existing Patient Deprecated

The dataset of the patient provided during token creation is modified as follows:

  • All fields and IDs that are included in the call with a non-empty value are set to the provided value.
  • Fields and IDs that are included in the call with an empty value (null or an empty string) are deleted. The field content is set to an empty string even if null is passed as input.
  • Fields and IDs that are not included in the call (i.e., the field name is not present as a key) are not changed.
  • Validation functions that affect the fields to be changed are applied. If date validation is configured, it may also consider non-changing fields (example: attempting to set the birth month to "02" for a patient with a birthdate of 30.01.2000 will fail). If any single validation fails, the entire call has no effect.
path Parameters
tokenId
required
string

Id of a valid "editPatient" token.

header Parameters
mainzellisteApiVersion
string

version of mainzelliste api.

Request Body schema: application/x-www-form-urlencoded
required
sureness
boolean
Default: false

Responses

DELETE patients/{tokenId}/{idType}/{idString} Deprecated

path Parameters
tokenId
required
string
idType
required
string
idString
required
string
query Parameters
withDuplicates
string

Responses

run a record linkage | EXPERIMENTAL

run a record linkage and return matched patient ids according to the given 'resultIds' in the token

query Parameters
tokenId
required
string

Id of a valid "checkMatch" token. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "checkMatch",
  "allowedUses": "10",
  "data": {
    "idtypes":["pid"]
  }
}
Request Body schema: application/x-www-form-urlencoded
required
fieldName
string
externalIdType
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

run a record linkage | EXPERIMENTAL Deprecated

run a record linkage and return matched patient ids according to the given 'resultIds' in the token

path Parameters
tokenId
required
string

Responses

POST ids/{idType}/ | EXPERIMENTAL

path Parameters
idType
required
string

type of ID to be generated

query Parameters
tokenId
required
string

Id of a valid "createIds" token. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "createIds",
  "allowedUses": "10",
  "data": {
    "searchIds": [
      {
       "idType": "pid",
       "idString": "A2W7EAA8"
      }
    ],
    "idTypes":["studyId"]
  }
}
header Parameters
mainzellisteApiVersion
string

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new session.

header Parameters
mainzellisteApiKey
required
string

Configurated API key for authentification.

Responses

Response samples

Content type
application/json
{}

Get existing session

path Parameters
sessionId
required
string

Responses

Response samples

Content type
application/json
{}

Delete existing session

path Parameters
sessionId
required
string

Responses

Create a new token.

create new token

path Parameters
sessionId
required
string

Id of a valid session.

header Parameters
mainzellisteApiKey
string

Key of mainzelliste API.

Request Body schema: application/json
required
type
string

Type of the token.

allowedUses
integer

Number of allowed uses of the token.

data
object

Further data about the token.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{ }

Get token related to session.

path Parameters
sessionId
required
string
tokenId
required
string

Responses

Delete specified token.

path Parameters
sessionId
required
string
tokenId
required
string

Responses

Create a new long running transaction.

Allows client to create a long running transaction.

query Parameters
tokenId
string

addPatients is the ony supported token. Create a valid token using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "addPatients",
  "data": {
    "idTypes":["pid"]
  }
}
Request Body schema: application/json
Array
fields
object

configured IDAT field

ids
object

list of external Ids. Multiple external ID type must given as an array

sureness
boolean
Default: false

This automate the decision, when an unsure match happen, and determine whether the tentative patient should be add or not. If true generate IDs as tentative (field "tentative") and also mark the patient as tentative to signal that a subsequent merge with an existing record is possible. Otherwise the request will be rejected

ignoreInvalidIDAT
boolean
Default: false

This allows adding patient with invalid IDAT for subsequent corrections. As the IDAT not suitable for record linkage an external ID would berequired to ensure a feature linkage with existing patients.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

try to poll the result of the job

path Parameters
jobId
required
string

use the jobId from the url returned in the location-Header of the response after calling 'POST /jobs'. e.g. http://{Mainzelliste-URL}/jobs/{jobId}/?tokenId={tokenId}

query Parameters
tokenId
string

user the same tokenId used to create the job.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

GET html/addPatient

query Parameters
tokenId
string

Responses

GET html/admin/editPatient

query Parameters
idType
string
idString
string

Responses

POST html/admin/editPatient

query Parameters
idType
string
idString
string

Responses

GET html/admin/viewAuditTrail

query Parameters
idType
string
idString
string

Responses

GET html/createPatient

query Parameters
tokenId
string

Responses

GET html/editPatient

query Parameters
tokenId
string

Responses

GET html/logo

Responses

Create fhir consent resource

fhir create interaction allows to create a new consent resource

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid addConsent token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "addConsent",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Request Body schema: application/json
required

Ensure that the provided patient identifier patient.identifier and the consent template Id in policy[x].uri exist. The provided logical Id will be ignored and a new one will be generated

Schema not provided

Responses

Request samples

Content type
application/json

R4 consent fhir resource

{
  • "resourceType": "Consent",
  • "id": "34150a23-b1c8-404f-874f-e042a30435d2",
  • "meta": {},
  • "status": "active",
  • "scope": {},
  • "category": [],
  • "patient": {},
  • "dateTime": "2020-09-01",
  • "organization": [
    ],
  • "policy": [
    ],
  • "provision": {
    }
}

Response samples

Content type
application/json

R4 consent fhir resource

{
  • "resourceType": "Consent",
  • "id": "34150a23-b1c8-404f-874f-e042a30435d2",
  • "meta": {},
  • "status": "active",
  • "scope": {},
  • "category": [],
  • "patient": {},
  • "dateTime": "2020-09-01",
  • "organization": [
    ],
  • "policy": [
    ],
  • "provision": {
    }
}

Conditional update of fhir consent resource

fhir conditional update interaction allows to update an existing resource based on two search criteria patient:identifier and policyUri, rather then the logical id consentId

query Parameters
patient:identifier
required
string
Example: patient:identifier=patient:identifier=id/pid|0007W0W9

relative or absolute path of an existing pseudonym. Format {path}/{idType}|{idString}

policyUri
required
string
Example: policyUri=policyUri=fhir/Questionnaire/2c513606-121d-487a-9262-becc163122ab

relative or absolute path of an existing consent template. Format {path}/{templateId}

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid editConsent token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "editConsent",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Request Body schema: application/json
required

Ensure that the provided patient identifier patient.identifier and the consent template Id in policy[x].uri exist.

Schema not provided

Responses

Request samples

Content type
application/json

R4 consent fhir resource

{
  • "resourceType": "Consent",
  • "id": "34150a23-b1c8-404f-874f-e042a30435d2",
  • "meta": {},
  • "status": "active",
  • "scope": {},
  • "category": [],
  • "patient": {},
  • "dateTime": "2020-09-01",
  • "organization": [
    ],
  • "policy": [
    ],
  • "provision": {
    }
}

Response samples

Content type
application/json

R4 consent fhir resource

{
  • "resourceType": "Consent",
  • "id": "34150a23-b1c8-404f-874f-e042a30435d2",
  • "meta": {},
  • "status": "active",
  • "scope": {},
  • "category": [],
  • "patient": {},
  • "dateTime": "2020-09-01",
  • "organization": [
    ],
  • "policy": [
    ],
  • "provision": {
    }
}

Search fhir consent resources

fhir search interaction allows to retrieve consent resources based on specific search criteria. Supported search parameters :

Name Type Description Example
category token classification of the consent statement category=http://loinc.org|57016-8
patient reference Support only identifier. Composite Search Parameters AND and OR are also supported patient:identifier=id/pid|0007W0W9,id/pid|000CU0WP&patient:identifier=id/pid|4102W0X5
mii-provision-provision-type token provision.type of each provisions with specified codes in mii-provision-provision-code parameter mii-provision-provision-type=permit
mii-provision-provision-code token Composite Search Parameters AND and OR are supported mii-provision-provision-code=urn:oid:2.16.840.1.113883.3.1937.777.24.5.3|2.16.840.1.113883.3.1937.777.24.5.3.1,urn:oid:2.16.840.1.113883.3.1937.777.24.5.3|2.16.840.1.113883.3.1937.777.24.5.3.10
mii-policy-uri uri policy.uri refers to an existing consent template mii-policy-uri=fhir/Questionnaire/2c513606-121d-487a-9262-becc163122ab
query Parameters
category
string
Example: category=category=http://loinc.org|57016-8

classification of the consent statement

patient:identifier
string
Example: patient:identifier=patient:identifier=id/pid|0007W0W9,id/pid|000CU0WP&patient:identifier=id/pid|4102W0X5

relative or absolute path of an existing pseudonym. Format {path}/{idType}|{idString}. Composite Search Parameters AND and OR are also supported

mii-policy-uri
string
Example: mii-policy-uri=mii-policy-uri=fhir/Questionnaire/2c513606-121d-487a-9262-becc163122ab

relative or absolute path of an existing consent template. Format {path}/{templateId}

mii-provision-provision-type
string
Example: mii-provision-provision-type=mii-provision-provision-type=permit

provision.type of each provisions with specified codes in mii-provision-provision-code parameter. Allowed values are permit or denied

mii-provision-provision-code
string
Example: mii-provision-provision-code=mii-provision-provision-code=urn:oid:2.16.840.1.113883.3.1937.777.24.5.3|2.16.840.1.113883.3.1937.777.24.5.3.1,urn:oid:2.16.840.1.113883.3.1937.777.24.5.3|2.16.840.1.113883.3.1937.777.24.5.3.10

provision.code parameter. Composite Search Parameters AND and OR are supported

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid readConsent token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "readConsent",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json

R4 Provenance fhir bundle

{}

Read fhir consent resource

fhir read interaction allows to retrieve a consent resource specified by their Id {consentId}

path Parameters
consentId
required
string
Example: d7a65ce8-2810-401a-b0db-70782a7b19a6

logical id of an existing resource

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid readConsent token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "readConsent",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json

R4 consent fhir resource

{
  • "resourceType": "Consent",
  • "id": "34150a23-b1c8-404f-874f-e042a30435d2",
  • "meta": {},
  • "status": "active",
  • "scope": {},
  • "category": [],
  • "patient": {},
  • "dateTime": "2020-09-01",
  • "organization": [
    ],
  • "policy": [
    ],
  • "provision": {
    }
}

Update of fhir consent resource

fhir update interaction create new version of an existing resource with the given id.

path Parameters
consentId
required
string
Example: d7a65ce8-2810-401a-b0db-70782a7b19a6

logical id of an existing resource.

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid editConsent token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "editConsent",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Request Body schema: application/json
required

Ensure that the provided patient identifier patient.identifier and the consent template Id in policy[x].uri exist.

Schema not provided

Responses

Request samples

Content type
application/json

R4 consent fhir resource

{
  • "resourceType": "Consent",
  • "id": "34150a23-b1c8-404f-874f-e042a30435d2",
  • "meta": {},
  • "status": "active",
  • "scope": {},
  • "category": [],
  • "patient": {},
  • "dateTime": "2020-09-01",
  • "organization": [
    ],
  • "policy": [
    ],
  • "provision": {
    }
}

Response samples

Content type
application/json

R4 consent fhir resource

{
  • "resourceType": "Consent",
  • "id": "34150a23-b1c8-404f-874f-e042a30435d2",
  • "meta": {},
  • "status": "active",
  • "scope": {},
  • "category": [],
  • "patient": {},
  • "dateTime": "2020-09-01",
  • "organization": [
    ],
  • "policy": [
    ],
  • "provision": {
    }
}

Delete fhir consent resource

fhir delete interaction allows to delete an existing consent resource

path Parameters
consentId
required
string
Example: d7a65ce8-2810-401a-b0db-70782a7b19a6

logical id of an existing resource

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid deleteConsent token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "deleteConsent",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Create DocumentReference resource (contains pdf scans)

fhir create interaction allows to create a new DocumentReference resource, contains a consent PDF scan encoded as base64 string in the element content[x].attachment.data

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid addConsentScan token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "addConsentScan",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Request Body schema: application/json
required

Ensure that the provided patient identifier subject.identifier exist. The provided logical Id will be ignored and a new one will be generated

Schema not provided

Responses

Request samples

Content type
application/json

R4 DocumentReference fhir resource

{}

Response samples

Content type
application/json

R4 DocumentReference fhir resource

{}

Get DocumentReference resource

fhir read interaction allows to retrieve a DocumentReference resource specified by their Id {documentReferenceId}

path Parameters
documentReferenceId
required
string
Example: d7a65ce8-2810-401a-b0db-70782a7b19a6

logical id of an existing resource

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid readConsentScan token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "readConsentScan",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json

R4 DocumentReference fhir resource

{}

Create Provenance resource (refers to a DocumentReference and contains signatures)

fhir create interaction allows to create a new Provenance resource that references a DocumentReference resource. This contains a consent PDF scan encoded as base64 string in the element content[x].attachment.data

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid addConsentProvenance token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "addConsentProvenance",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Request Body schema: application/json
required

Ensure that the provided consent reference target[x].reference and the DocumentReference entity[x].what.referenceexist and belong to the same patient. The provided logical Id will be ignored and a new one will be generated.

Schema not provided

Responses

Request samples

Content type
application/json

R4 Provenance fhir resource

{
  • "resourceType": "Provenance",
  • "id": "55a994005e3111efab62b9a6cea9aa68",
  • "meta": {},
  • "target": [
    ],
  • "recorded": "2020-12-11T09:39:07+00:00",
  • "agent": [
    ],
  • "entity": [
    ],
  • "signature": [
    ]
}

Response samples

Content type
application/json

R4 Provenance fhir resource

{
  • "resourceType": "Provenance",
  • "id": "55a994005e3111efab62b9a6cea9aa68",
  • "meta": {},
  • "target": [
    ],
  • "recorded": "2020-12-11T09:39:07+00:00",
  • "agent": [
    ],
  • "entity": [
    ],
  • "signature": [
    ]
}

Search Provenance resources

fhir search interaction allows to retrieve provenance resources based on target search criteria.

query Parameters
target
string
Example: target=target=Consent/{consentId}/_history/{versionNumber}

consent reference. Support only target.reference

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid searchConsentProvenances token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "searchConsentProvenances",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json

R4 Provenance fhir bundle

{}

Retrieves all consent policy sets

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid searchConsentPolicySets token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "searchConsentPolicySets",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json
{}

Creates new consent policy set

header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid addConsentPolicySet token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "addConsentPolicySet",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Request Body schema: application/json
id
string

policy set identifier

name
string

policy set name

Responses

Request samples

Content type
application/json
{
  • "id": "MII_Value_Set",
  • "name": "MII Value Set"
}

Response samples

Content type
application/json
{}

Retrieves a specific consent policy set by their Id {policySetId}

path Parameters
policySetId
required
string
header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid readConsentPolicySet token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "readConsentPolicySet",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json
{}

Deletes a specific consent policy set by their Id {policySetId}

path Parameters
policySetId
required
string
header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid deleteConsentPolicySet token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "deleteConsentPolicySet",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Retrieves a list a consent policies associated to a specific policy set

path Parameters
policySetId
required
string
header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid searchConsentPolicies token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "searchConsentPolicies",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

Response samples

Content type
application/json
{}

Creates new consent policy belonging to a policy set identified by {policySetId}

path Parameters
policySetId
required
string
header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid addConsentPolicy token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "addConsentPolicy",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Request Body schema: application/json
required
code
string

policy identifier

text
string

plain text representation

Responses

Request samples

Content type
application/json
{
  • "code": "2.16.840.1.113883.3.1937.777.24.5.3.2",
  • "text": "IDAT erheben"
}

Response samples

Content type
application/json
{}

Deletes a specific consent policy by their Id {policyId} belonging to a policy set identified by `{policySetId}`

path Parameters
policySetId
required
string
policyId
required
string
header Parameters
Authorization
required
string
Example: MainzellisteToken d4f6c78a-a157-44f3-aae2-aee5d6092f57

MainzellisteToken {tokenId}. {tokenId} is a valid deleteConsentPolicy token id. This can be created using sessions/{sessionId}/tokens endpoint. e.g.:

{
  "type": "deleteConsentPolicy",
}
mainzellisteApiVersion
string
Example: 3.4

Version of Mainzelliste API.

Responses

total number of add patient requests | EXPERIMENTAL

query Parameters
start
string
end
string

Responses

total number of patients | EXPERIMENTAL

Responses

total number of tentative patients | EXPERIMENTAL

Responses

cpu information | EXPERIMENTAL

Responses

used memory | EXPERIMENTAL

Responses

GET configuration/fieldKeys | EXPERIMENTAL

Resource for querying configuration parameters via the REST interface. This resource is for internal use and subject to change.

Responses

Response samples

Content type
application/json
[
  • "string"
]