Skip to content

DIGG API Integration Guide

A practical guide for integration partners using the DIGG (Digitale Geburtsanzeige) API.

Version: 0.2.0 Last Updated: 2026-03-09

Table of Contents

  1. Introduction
  2. Authentication
  3. Core Concepts
  4. Memento Endpoint
  5. Report Retrieval Endpoints
  6. Error Handling
  7. Reference

Introduction

The DIGG API enables hospital information systems (KIS) to pre-fill digital birth registration forms (Geburtsanzeige) for the civil registry office (Standesamt) via xPersonenstand integration. This API allows integration partners to:

  • Create form mementos to generate pre-filled form URLs from hospital birth data
  • Enable user review by hospital staff or midwives before official submission
  • Retrieve report results and status after end users submit forms to the Standesamt

Use Case

DIGG solves the digital transmission of a Geburtsanzeige:

  1. Hospital system (KIS) has birth data but wants staff to review and complete the form before xPersonenstand submission
  2. System calls API with birth report data as JSON
  3. API returns an encrypted memento string
  4. System uses the memento to open a prefilled form
  5. User reviews, completes missing info, applies digital signature/seal, and submits to the Standesamt
  6. System automatically polls for the processing status and signed confirmation PDF
KIS / Hospital System
    ↓
[1] POST /api/digg/v1/memento  (API user credentials)
    ↓
[2] Receives { "memento": "...", "magicLink": "/mtl/.../digg/Geburtsbescheinigung?m=..." }
    ↓
[3] Constructs absolute URL: https://elim.vertamob.de + magicLink
    ↓
[4] Opens URL in browser — authenticated via MTL token
    ↓
End User
    ↓
[6] Reviews pre-filled data, completes form, applies signature/seal → submits to Standesamt
    ↓
KIS / Hospital System (asynchronous)
    ↓
[7] GET /api/digg/v1/reports/{id}  → status (PENDING, SUCCESS, FAILURE) + receipt PDF

Benefits:

  • No direct automated submission — users maintain control and can review/correct data
  • Form validation happens in browser (immediate feedback)
  • Secure, encrypted mementos protect sensitive parent/child data

Prerequisites

Before using the API, you need:

  • API User Credentials: Username and password provided by your administrator
  • Seal or Signature: You have to create a seal or signature and deposit it at https://elim.vertamob.de/home/signaturen

OpenAPI Specification

The complete OpenAPI specification is available at:

https://elim.vertamob.de/api/docs/swagger-ui/index.html?urls.primaryName=DIGG

Authentication

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

Example

curl -u "api-username:api-password" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"id":"DIGG-2026-001"}' \
  https://elim.vertamob.de/api/digg/v1/memento

Core Concepts

Geburtsanzeige

The main data structure for birth registration reporting. Key fields include:

  • id (required): Unique report identifier for tracking
  • standortId: ID of the reporting hospital
  • nameEinrichtung: Name of the hospital
  • ansprechpartner: Contact name
  • anschriftAutor: Hospital Address
  • geburtsangaben: Details about time and place of birth
  • kind: Child's gender and names
  • mutter: Mother's standard or confidential data (vertrauliche Geburt)
  • elternteil2: Optional secondary parent data
  • zuordnungGeburtsanzeige: Identifier for further official references

Digital Signature (Siegel / Signatur)

Submitting a birth registration to the Standesamt via xPersonenstand legally requires a valid digital signature or seal. If a seal is available it will be applied automatically, otherwise the end user will be prompted to apply this signature directly within the DIGG form interface prior to final submission. This step is mandatory; a report cannot be sent without it.

Memento Pattern

A memento is an encrypted, URL-safe string that contains form pre-fill data:

  • Generated from JSON hospital report data
  • Tamper-proof and URL-safe
  • Used as query parameter: ?m={memento}

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 /digg/Geburtsbescheinigung?m={memento} on success - Is a relative path — prepend your instance host to make it absolute

magicLink: "/mtl/eyJ...token.../digg/Geburtsbescheinigung?m=eyJ...memento..."

Full URL: https://elim.vertamob.de/mtl/eyJ...token.../digg/Geburtsbescheinigung?m=eyJ...memento..."

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

Report ID

The id field must be unique per API user. It serves a dual purpose:

  1. Form pre-fill and correlation: Correlates the hospital data to the form
  2. Status retrieval key: After submission, used to retrieve delivery status via GET /api/digg/v1/status/{id}

Memento Endpoint

Endpoint: POST /api/digg/v1/memento

Purpose: Create encrypted memento string and magic link to pre-fill DIGG reporting forms.

Request Body

Only id is required; all other fields are optional to allow partial pre-filling.

Minimal Example:

{
  "id": "DIGG-2026-00001"
}

Complete Example:

{
  "id": "DIGG-2026-00123",
  "standortId": "770001",
  "nameEinrichtung": "Universitätsklinikum Musterstadt",
  "anschriftAutor": {
    "gebaeude": {
      "postleitzahl": "10117",
      "strasse": "Musterstraße",
      "hausnummer": "1",
      "wohnort": "Berlin"
    }
  },
  "totgeburt": false,
  "vertraulicheGeburt": false,
  "geburtsangaben": {
    "tag": "2026-02-23",
    "uhrzeit": "14:30",
    "ort": {
      "strasse": "Klinikstraße",
      "hausnummer": "1",
      "ort": "Musterstadt"
    }
  },
  "kind": {
    "geschlecht": "WEIBLICH",
    "name": {
      "vornamen": "Emma Sophie",
      "familienname": "Mustermann"
    }
  },
  "mutter": {
    "standard": {
      "name": {
        "vornamen": "Anna",
        "familienname": "Mustermann",
        "geburtsname": "Schmidt"
      },
      "geburtsdatum": "1990-05-15",
      "anschrift": {
        "strasse": "Musterweg",
        "hausnummer": "12",
        "postleitzahl": "12345",
        "wohnort": "Musterstadt"
      }
    }
  }
}

Response

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

{
  "memento": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..DGG5lQvJC8OpYrCt.Xm8YR...",
  "magicLink": "/mtl/eyJ...token.../digg/Geburtsbescheinigung?m=eyJ...memento..."
}
Field Type Nullable Description
memento string No Encrypted, URL-safe string containing report data. Use as ?m={memento} query parameter.
magicLink string Yes Relative URL for authenticated single-click access. Prepend your instance host: https://elim.vertamob.de + magicLink

Report Retrieval Endpoints

DIGG reports are delivered asynchronously via xPersonenstand/XTA2 transport.

GET /reports — List pending report IDs

Endpoint: GET /api/digg/v1/reports

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

Request:

curl -u "api-user:api-pass" \
  https://elim.vertamob.de/api/digg/v1/reports

Response (200):

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

An empty array [] means no submissions are pending retrieval.

GET /reports/{id} — Retrieve report result

Endpoint: GET /api/digg/v1/reports/{id}

Parameters:

  • id (path, required)
  • peek (query, optional): true for non-destructive read. Default: false.

Non-destructive peek:

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

Response (200 — SUCCESS):

{
  "id": "DIGG-2026-00123",
  "status": "SUCCESS",
  "module": "DIGG",
  "submittedAt": "2026-02-23T14:32:00Z",
  "portal": "StandesamtPortal",
  "receiptPdf": "JVBERi0xLjQK...",
  "failureReason": null
}

Status semantics:

  • PENDING: Sent but delivery not yet confirmed. Not marked as polled.
  • SUCCESS: Successfully delivered to receiver. Contains receiptPdf (base64).
  • FAILURE: Transport failed. Contains failureReason.

Note: By default, reading a SUCCESS or FAILURE report is destructive (it is marked as polled and disappears from future calls unless ?peek=true is used).

Error Handling

HTTP Status Codes

Code Status Meaning
200 OK Request successful
400 Bad Request Invalid JSON or validation error
401 Unauthorized Missing or invalid API credentials
404 Not Found Report ID does not exist
410 Gone Report was already retrieved (use ?peek=true to avoid)

Validation Errors

If the request data is invalid (e.g. missing id), a 400 Bad Request is returned:

{
  "errors": ["id must not be null"]
}

Reference

API Endpoints Summary

Method Endpoint Description
POST /api/digg/v1/memento Create memento
GET /api/digg/v1/reports/{id} Retrieve report delivery status

Date & Time Format

  • Date: ISO 8601 format (YYYY-MM-DD, e.g., 2026-02-23)
  • Time: ISO 8601 format (HH:mm, e.g., 14:30)

Gender Enum Values

Value Description
MAENNLICH Male
WEIBLICH Female
UNBESTIMMT Unspecified

Document Version: 0.2.0 Last Updated: 2026-03-09 API Version: v1