ELIM API Integration Guide

A practical guide for integration partners using the ELIM (Hospitalisierungsmeldung) API.

Version: 0.1.0 Last Updated: 2026-03-25

Introduction

The ELIM API enables hospital information systems (KIS) to pre-fill disease notification forms (Hospitalisierungsmeldung) in Germany (DEMIS integration). This API allows integration partners to:

Create form mementos to generate pre-filled form URLs from hospital data
Retrieve report results after end users submit forms to DEMIS
Enable user review before submission to public health authorities

Use Case

ELIM solves a common integration pattern:

Hospital system (KIS) has patient and reporting data but wants users to review before DEMIS submission
System calls API with hospital report data as JSON
API returns an encrypted memento string and a ready-to-use magicLink URL
System sends the magicLink to the end user (email, portal, etc.)
User clicks the link — authenticated, lands on ELIM index with pre-filled data
User selects disease form, reviews, and submits to DEMIS

KIS / Hospital System
    ↓
[1] POST /api/elim/v1/memento  (API user credentials)
    ↓
[2] Receives { "memento": "...", "magicLink": "/mtl/.../elim/?m=..." }
    ↓
[3] Constructs absolute URL: https://your-instance + magicLink
    ↓
[4] Delivers URL to end user (email, portal link, SMS, etc.)
    ↓
End User
    ↓
[5] Clicks link → authenticated via MTL token
    → lands on pre-filled form
    ↓
[6] Reviews pre-filled data → submits to DEMIS
    ↓
KIS / Hospital System (asynchronous)
    ↓
[7] GET /api/elim/v1/reports  → list of pending reportIds
[8] GET /api/elim/v1/reports/{reportId}  → full result + receipt PDF

Benefits: - No direct submission required — users maintain control - No separate end-user login credentials needed — magicLink handles authentication - Form validation happens in browser (immediate feedback) - Users can correct or supplement data before sending - Encrypted mementos are tamper-proof

Prerequisites

Before using the API, you need: - API User Credentials: Username and password provided by your administrator - Base URL: Your ELIM instance URL (e.g., https://elim.vertamob.de)

That's it. End users do not need separate credentials — the magicLink in the API response handles their authentication automatically.

DEMIS registration and certificate (per facility)

For the actual submission to DEMIS, the reporting facility needs its own DEMIS registration. DEMIS issues a certificate (a PKCS12 file with a passphrase) which is deposited in ELIM per site and per environment (test and production separately). An SMC-B is not required — authentication towards DEMIS runs exclusively over the DEMIS certificate.

Attribution: on the transport level, each report is cryptographically attributed to the facility holding the certificate. The reporting doctor is transmitted as content of the report (name, LANR, contact details) and is documented in the report and the RKI receipt, but is not separately cryptographically signed.

API Versioning

All endpoints are versioned under /api/elim/v1/.

OpenAPI Specification

The complete OpenAPI specification is available at:

https://your-instance/api/docs/swagger-ui/index.html?urls.primaryName=ELIM

Authentication

The API uses HTTP Basic Authentication with your API user credentials (the service account provided by your administrator). End users do not need separate credentials.

How It Works

Your administrator creates an API user account with username and password
For each API request, provide credentials in the Authorization header
The API returns a magicLink in the response — a server-issued token that grants end users one-time authenticated access to the pre-filled form

Example

curl -u "api-username:api-password" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"MeldeId":"ELIM-2026-001"}' \
  https://elim.example.com/api/elim/v1/memento

The response contains both the encrypted memento and a ready-to-use magicLink — no further credentials are needed for the end user.

See Magic Token Link (MTL) for details on how the server-issued token works.

Core Concepts

Disease Notification (Hospitalisierungsmeldung)

The main data structure for hospital disease reporting. Contains: - MeldeId: Unique hospital report identifier - Patient: Patient information - MedizinischeInformationen: Medical details (onset, diagnosis date) - KlinischeAngaben: Clinical information (hospitalization, death, intensive care) - MeldendeEinrichtung: Reporting facility - Arzt: Reporting doctor

Memento Pattern

A memento is an encrypted, URL-safe string that contains form pre-fill data: - Generated from JSON disease notification data - Encrypted with AES-256-GCM using your API user's KEK - Tamper-proof and URL-safe - Typical size: 500–2000 characters - Used as query parameter: ?m={memento}

Magic Token Link (MTL)

The magicLink field in the API response is a server-issued, time-limited URL that: - Authenticates the end user automatically (no login page) - Redirects to /elim/forms/{memento} on success or specifically configured form routes - Is a relative path — prepend your instance host to make it absolute

magicLink: "/mtl/eyJ...token.../elim/forms/eyJ...memento..."

Full URL: https://elim.example.com/mtl/eyJ...token.../elim/forms/eyJ...memento..."

See Magic Token Link (MTL) for security details and token lifetime.

Report ID

The reportId in the report retrieval endpoints is your MeldeId — identical value, no re-keying. You correlate results directly against your own identifier; no additional correlation key exists or is needed.

Three rules to build on:

Always supply your own MeldeId. If it is missing, the form generates a random UUID when opened — which your system can then no longer correlate.
A MeldeId is single-use. After a successfully submitted report, a new submission under the same id is rejected (protection against double reporting). Use a fresh id for each new report.
A retrievable report only exists after successful submission by the end user. Before that, GET /reports/{reportId} returns 404 — see 404 semantics below.

Memento Endpoint

Endpoint: POST /api/elim/v1/memento

Purpose: Create encrypted memento string and magic link to pre-fill disease notification forms.

Request Body

The endpoint accepts Hospitalisierungsmeldung data as JSON. All fields are optional for partial pre-filling.

Minimal Example:

{}

Complete Example:

{
  "MeldeId": "ELIM-2026-00123",
  "MeldeDatum": "2026-03-20",
  "Patient": {
    "Vorname": "Max",
    "Name": "Mustermann",
    "Geburtsdatum": "1980-05-15",
    "Geschlecht": "MAENNLICH",
    "Adresse": {
      "Strasse": "Musterstraße",
      "Hausnummer": "123",
      "PLZ": "12345",
      "Stadt": "Musterstadt",
      "inDeutschland": true
    },
    "Kontakt": {
      "Telefon": "+49 123 456789",
      "Email": "max.mustermann@example.com"
    }
  },
  "KlinischeAngaben": {
    "Hospitalisiert": "YES",
    "Hospitalisierung": {
      "AufnahmeAm": "2026-03-18",
      "EntlassungAm": null,
      "IntensivBehandlung": false
    }
  },
  "MeldendeEinrichtung": {
    "Name": "Universitätsklinikum Musterstadt",
    "BSNR": "123456789",
    "IK_Nummer": "987654321",
    "Adresse": {
      "Strasse": "Klinikstraße 1",
      "PLZ": "12345",
      "Stadt": "Musterstadt",
      "Land": "DE"
    }
  },
  "Arzt": {
    "Titel": "Dr.",
    "Vorname": "Anna",
    "Nachname": "Schmidt",
    "LANR": "123456789",
    "Kontakt": {
      "Telefon": "+49 123 456750"
    }
  }
}

Response

Returns a JSON object containing the encrypted memento and a ready-to-use magic link:

{
  "memento": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..DGG5lQvJC8OpYrCt.Xm8YR...",
  "magicLink": "/mtl/eyJ...token.../elim/forms/eyJ...memento..."
}

Note: magicLink is null if the API user has no authentication configuration that supports token generation.

Detecting submission success from an embedding client

If you embed the ELIM form in a browser component (KIS container, modal plugin, iframe wrapper), you can detect the outcome from the URL alone:

Success: after a successful submission, the server responds with an HTTP 302 redirect to /elim/hospitalisierungsmeldung/success — a static, parameterless URL.
Failure: no redirect happens. The form is re-rendered with HTTP 400 and an error message; the URL stays the form URL.

Success and failure are therefore reliably distinguishable from the URL. For the full outcome including the RKI receipt PDF, fetch GET /api/elim/v1/reports/{reportId} after seeing the redirect.

Report Retrieval Endpoints

After an end user submits the report via the ELIM form, the submission result is stored and made available for retrieval by the API user that created the original memento.

Timing: submission to DEMIS happens synchronously when the user sends the form — the result including the RKI receipt is retrievable as soon as the user sees the success page. There is no window in which a submitted report is still "in flight".

Retention: unretrieved results are kept for 3 days; a nightly cleanup removes the payload including the RKI receipt after that. Retrieve results within this window — typically one fetch right after the success redirect.

GET /reports — List pending report IDs

Endpoint: GET /api/elim/v1/reports

Returns an array of reportId strings for reports that have been submitted to DEMIS but not yet retrieved. Reports disappear from this list once retrieved without ?peek=true.

Request:

curl -u "api-user:api-pass" \
  https://elim.example.com/api/elim/v1/reports

Response (200):

["ELIM-2026-00123", "ELIM-2026-00124"]

GET /reports/{reportId} — Retrieve report result

Endpoint: GET /api/elim/v1/reports/{reportId}

Returns the full result for a submitted report, including the RKI receipt PDF for successful submissions.

Parameters:

Parameter	In	Required	Description
`reportId`	path	Yes	The report ID from the submission
`peek`	query	No	`true` = non-destructive read. Default: `false`

Non-destructive peek:

curl -u "api-user:api-pass" \
  "https://elim.example.com/api/elim/v1/reports/ELIM-2026-00123?peek=true"

Response (200):

{
  "reportId": "ELIM-2026-00123",
  "status": "SUCCESS",
  "module": "ELIM",
  "diseaseCode": "Influenza",
  "description": "Hospitalisierungsmeldung Influenza",
  "submittedAt": "2026-03-20T14:32:00Z",
  "receiptPdf": "JVBERi0xLjQK..."
}

Only SUCCESS is ever reported here — a retrievable report is a confirmed submission. Failures are never delivered through this API: a failed attempt is shown to the user in the form, where it is corrected and retried; until a submission succeeds, the id simply has no report and answers 404 (see below).

404 semantics

A 404 from GET /reports/{reportId} means one of:

the report was not yet submitted by the end user (the normal state between memento creation and user action — it can last hours or days),
the MeldeId is unknown,
the MeldeId belongs to a different API user,
the report expired (older than the 3-day retention window).

These cases are not distinguishable by the status code alone. In particular: a 404 right after creating a memento is expected, not an error.

Polling pattern

Reports become available when the end user completes and submits the form — if your client detects the success redirect, fetch the result event-driven right after it and polling becomes largely unnecessary. As a cyclic safety net, once per minute against GET /reports is more than sufficient. There are currently no rate limits, but keep the cadence moderate. Timeouts of 10–30 seconds are plenty; note the result carries the receipt PDF base64-encoded and can be a few hundred kilobytes.

# Poll for new reports every 60 seconds
while true; do
  IDS=$(curl -s -u "api-user:api-pass" \
    "https://elim.example.com/api/elim/v1/reports" | jq -r '.[]')

  for ID in $IDS; do
    RESULT=$(curl -s -u "api-user:api-pass" \
      "https://elim.example.com/api/elim/v1/reports/$ID")
    STATUS=$(echo "$RESULT" | jq -r '.status')
    echo "$ID: $STATUS"

    if [ "$STATUS" = "SUCCESS" ]; then
      echo "$RESULT" | jq -r '.receiptPdf' | base64 --decode > "${ID}.pdf"
    fi
  done

  sleep 60
done

Complete Workflow Examples

Workflow 1: Complete external integration

#!/bin/bash
# Complete workflow for KIS/hospital system integration with ELIM

BASE_URL="https://elim.example.com"
API_USER="kis-api"
API_PASS="api-secret"

# Step 1: Create memento and get magic link
echo "Creating memento via API..."
RESPONSE=$(curl -s -X POST \
  -u "$API_USER:$API_PASS" \
  -H "Content-Type: application/json" \
  -d '{
    "MeldeId": "ELIM-2026-00123",
    "MeldeDatum": "2026-03-20",
    "Patient": {
      "Vorname": "Max",
      "Name": "Mustermann",
      "Geburtsdatum": "1980-05-15",
      "Geschlecht": "MAENNLICH"
    },
    "MeldendeEinrichtung": {
      "Name": "Universitätsklinikum Musterstadt",
      "BSNR": "123456789"
    }
  }' \
  "$BASE_URL/api/elim/v1/memento")

MAGIC_LINK=$(echo "$RESPONSE" | jq -r '.magicLink')

if [ -z "$MAGIC_LINK" ] || [ "$MAGIC_LINK" = "null" ]; then
  echo "Error: No magic link in response"
  echo "$RESPONSE" | jq .
  exit 1
fi

# Step 2: Construct absolute URL
FORM_URL="$BASE_URL$MAGIC_LINK"

# Step 3: Deliver to end user
echo ""
echo "Form URL for end user (single-click, no login required):"
echo "$FORM_URL"
echo ""
echo "What happens when user clicks:"
echo "1. MTL token authenticates the user automatically"
echo "2. Redirects to pre-filled ELIM form"
echo "3. User reviews and submits to DEMIS"

Error Handling

HTTP Status Codes

Code	Status	Meaning
200	OK	Request successful
400	Bad Request	Invalid JSON or validation error (memento endpoint)
401	Unauthorized	Missing or invalid API credentials
404	Not Found	Not yet submitted by the user, unknown ID, different user's ID, or expired — see 404 semantics
410	Gone	Report was already retrieved (use `?peek=true` to avoid)
500	Internal Server Error	Server error (contact support)

Follow-up and correction reports

Discharge, death and intensive care are fields within the report and can be transmitted there (Hospitalisierung.EntlassungAm, KlinischeAngaben.Verstorben/Todesdatum, Hospitalisierung.IntensivBehandlung/IntensivBehandlungVon, Hospitalisierung.ArtDerHospitalisierung). A "Verlegung" (transfer) field does not exist in the data model.

ELIM does not currently support a dedicated follow-up or correction report with a machine-readable reference to the original report. If facts change after submission, submit a new report with a new MeldeId.

Validation Errors

If the request data is invalid, you'll receive a 400 Bad Request with details:

Response (400):

{
  "errors": ["MeldeDatum must be a valid date"]
}

Reference

API Endpoints Summary

Method	Endpoint	Description
POST	`/api/elim/v1/memento`	Create encrypted memento and magic link for form pre-fill
GET	`/api/elim/v1/reports`	List pending (unpolled) report IDs
GET	`/api/elim/v1/reports/{reportId}`	Retrieve full report result (status, receipt PDF)

OpenAPI Specification

Interactive API documentation (Swagger UI):

https://your-instance/api/docs/swagger-ui/index.html?urls.primaryName=ELIM

Date Format

All dates use ISO 8601 format:

YYYY-MM-DD
Example: 2026-03-20

Security Notes

Memento Encryption: - Mementos are encrypted with AES-256-GCM using your API user's KEK - Each memento is unique even for identical data - Tampering is detected and rejected

Magic Link Security: - Tokens are server-issued and signed - Each token is single-use and time-limited

Best Practices: - ✓ Generate the magic link close to the time of sending - ✗ Do not expose mementos or magic links to unauthorized users - ✗ Do not reuse magic links; generate a fresh one for each workflow run

Document Version: 0.2.0 Last Updated: 2026-08-11 API Version: v1

ELIM API Integration Guide

Table of Contents

Introduction

Use Case

Prerequisites

DEMIS registration and certificate (per facility)

API Versioning

OpenAPI Specification

Authentication

How It Works

Example

Core Concepts

Disease Notification (Hospitalisierungsmeldung)

Memento Pattern

Magic Token Link (MTL)

Report ID

Memento Endpoint

Request Body

Response

Detecting submission success from an embedding client

Report Retrieval Endpoints

GET /reports — List pending report IDs

GET /reports/{reportId} — Retrieve report result

404 semantics

Polling pattern

Complete Workflow Examples

Workflow 1: Complete external integration

Error Handling

HTTP Status Codes

Follow-up and correction reports

Validation Errors

Reference

API Endpoints Summary

OpenAPI Specification

Date Format

Security Notes