Clone wiki

Mainzelliste / External-IDs

Using externally generated IDs

Starting with API version 3.0 (first implemented in Mainzelliste version 1.7.0), IDs can be provided from an external source instead of being generated by Mainzelliste itself. In order to use this feature, requests must specify API version 3.0 or greater by setting the HTTP header or URL parameter mainzellisteApiVersion to value 3.0.


To define an externally generated ID type, use the pseudo generator ExternalIDGenerator in the configuration file. For example, the following configuration defines an internally generated ID type pid and an externally provided ID type labId:

idgenerators = pid, extid = PIDGenerator = 1 = 2 = 3

idgenerator.extid = ExternalIDGenerator

The name of the ID type must not equal a field name.

Externally generated ID types can be added to the configuration at any time (restart the application to activate the changes), but of course an externally generated ID of a patient will be undefined before it is explicitely set.

Setting externally generated IDs

Via addPatient token

Externally generated IDs can be set as key-value pairs (ID type -> ID value) in data item ids, e.g.:


Via POST /patients

In the request to create a patient (POST /patients), externally generated IDs can be submitted as key-value pairs in the same way as fields. For example, in order to set the ID of type labId to the value 12345, add the request parameter labId=12345.

Via PUT /patients/... (editing a patient)

To allow changing an externally generated ID via an edit request (PUT /patients/...), the respective ID type must be listed under data element ids in the editPatient token, e.g.:

  "type": "editPatient",
  "data": {

In the actual edit request, the ID is submitted as key-value-pair (ID type -> ID value) such as in the create request (POST /patients, see above).