API docs by Redocly

mainzelliste API (3.3.0 DRAFT)

Download OpenAPI specification:Download

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

mainzelliste API

Find more info here

Output status information as JSON.

Responses

Response samples

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

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

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 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
[
  • {
    },
  • {
    }
]

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

run a record linkage | EXPERIMENTAL

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

path Parameters
tokenId
required
string

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

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.

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.
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

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.

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